asset.list

Retrieve lists of assets with filtering options

The asset.list method allows you to retrieve bulk lists of assets that ChainPatrol has reviewed, with powerful filtering options by type, status, and date range. This method is ideal for bulk analysis and reporting.

API Reference

Method Signature

client.asset.list(request: AssetListInput): Promise<AssetListOutput>

Parameters

request · AssetListInput · required

The asset list request object with filtering criteria.

Show AssetListInput Properties

type · enum<string> · required

The type of assets to retrieve.

Supported types: URL, PAGE, ADDRESS.

status · enum<string> · required

Filter assets by their threat status.

Supported statuses: BLOCKED, ALLOWED, UNKNOWN.

startDate · string · required

Start date for the query range in YYYY-MM-DD format.

endDate · string · required

End date for the query range in YYYY-MM-DD format.

Must be greater than or equal to startDate.

organizationSlug · string

Optional organization slug to filter assets for a specific organization.

Returns

assets · array · required

Array of asset objects matching the filter criteria.

Show Asset Object Properties

type · enum<string> · required

The type of the asset: URL, PAGE, or ADDRESS.

content · string · required

The content of the asset:

• For URL/PAGE: The URL of the asset
• For ADDRESS: The wallet or contract address

status · enum<string> · required

The threat status: UNKNOWN, ALLOWED, or BLOCKED.

updatedAt · string · required

ISO timestamp when the asset was last updated.

reason · string · deprecated

Deprecated: The reason for the status classification. This field is deprecated and should not be used in new implementations.

Filtering Options

By Asset Type

Filter by URL, PAGE, or ADDRESS to focus on specific asset categories.

By Status

Filter by BLOCKED, ALLOWED, or UNKNOWN status.

By Date Range

Specify start and end dates to analyze specific time periods.

By Organization

Use organizationSlug to get organization-specific results.

Getting Started

Quick Start

Basic List Query

import { ChainPatrolClient } from "@chainpatrol/sdk";

const client = new ChainPatrolClient({
apiKey: "cp_live_your_api_key_here",
});

const result = await client.asset.list({
type: "URL",
status: "BLOCKED",
startDate: "2023-01-01",
endDate: "2023-12-31",
});

console.log(`Found ${result.assets.length} blocked URLs`);

Basic Usage Patterns

// Get recent threats
async function getRecentThreats(days: number = 7) {
  const endDate = new Date().toISOString().split("T")[0];
  const startDate = new Date(Date.now() - days * 24 * 60 * 60 * 1000)
    .toISOString()
    .split("T")[0];

  return await client.asset.list({
    type: "URL",
    status: "BLOCKED",
    startDate,
    endDate,
  });
}

// Count assets by status
async function getAssetStats(dateRange: { start: string; end: string }) {
  const [blocked, allowed] = await Promise.all([
    client.asset.list({
      type: "URL",
      status: "BLOCKED",
      startDate: dateRange.start,
      endDate: dateRange.end,
    }),
    client.asset.list({
      type: "URL",
      status: "ALLOWED",
      startDate: dateRange.start,
      endDate: dateRange.end,
    }),
  ]);

  return {
    blocked: blocked.assets.length,
    allowed: allowed.assets.length,
  };
}

Implementation Guide

Use Cases & Patterns

Threat Intelligence Reports

Generate periodic reports on blocked assets for security analysis.

async function generateThreatReport(month: string) {
  const startDate = `${month}-01`;
  const endDate = `${month}-31`;
  
  const threats = await client.asset.list({
    type: "URL",
    status: "BLOCKED",
    startDate,
    endDate,
  });
  
  // Group by update date
  const byDate = threats.assets.reduce((acc, asset) => {
    const date = asset.updatedAt.split('T')[0];
    acc[date] = (acc[date] || 0) + 1;
    return acc;
  }, {} as Record<string, number>);
  
  return {
    total: threats.assets.length,
    dailyBreakdown: byDate,
    period: `${startDate} to ${endDate}`,
  };
}

Compliance Auditing

Export asset data for compliance and audit requirements.

async function exportComplianceData(orgSlug: string, year: string) {
  const result = await client.asset.list({
    type: "ADDRESS",
    status: "BLOCKED",
    startDate: `${year}-01-01`,
    endDate: `${year}-12-31`,
    organizationSlug: orgSlug,
  });
  
  return result.assets.map(asset => ({
    address: asset.content,
    blockedDate: asset.updatedAt,
    organization: orgSlug,
  }));
}

Trend Analysis

Analyze threat trends over time by comparing different date ranges.

async function analyzeTrends() {
  const currentMonth = await client.asset.list({
    type: "URL",
    status: "BLOCKED",
    startDate: "2024-02-01",
    endDate: "2024-02-29",
  });
  
  const previousMonth = await client.asset.list({
    type: "URL", 
    status: "BLOCKED",
    startDate: "2024-01-01",
    endDate: "2024-01-31",
  });
  
  const change = currentMonth.assets.length - previousMonth.assets.length;
  const percentChange = (change / previousMonth.assets.length) * 100;
  
  return {
    current: currentMonth.assets.length,
    previous: previousMonth.assets.length,
    change,
    percentChange: Math.round(percentChange * 100) / 100,
  };
}

Bulk Analysis

async function analyzeThreats(timeRange: { start: string; end: string }) {
  const [blockedUrls, blockedAddresses, allowedUrls] = await Promise.all([
    client.asset.list({
      type: "URL",
      status: "BLOCKED",
      startDate: timeRange.start,
      endDate: timeRange.end,
    }),
    client.asset.list({
      type: "ADDRESS",
      status: "BLOCKED",
      startDate: timeRange.start,
      endDate: timeRange.end,
    }),
    client.asset.list({
      type: "URL",
      status: "ALLOWED",
      startDate: timeRange.start,
      endDate: timeRange.end,
    }),
  ]);

  return {
    blockedUrls: blockedUrls.assets.length,
    blockedAddresses: blockedAddresses.assets.length,
    allowedUrls: allowedUrls.assets.length,
  };
}

Data Export & Processing

async function exportThreats(outputFormat: "csv" | "json" = "json") {
  const threats = await client.asset.list({
    type: "URL",
    status: "BLOCKED",
    startDate: "2024-01-01",
    endDate: "2024-12-31",
  });

  const processedData = threats.assets.map((asset) => ({
    url: asset.content,
    status: asset.status,
    lastUpdated: asset.updatedAt,
  }));

  if (outputFormat === "csv") {
    // Convert to CSV format
    const headers = Object.keys(processedData[0]).join(",");
    const rows = processedData.map((row) => Object.values(row).join(","));
    return [headers, ...rows].join("\n");
  }

  return processedData;
}

Technical Details

Format Requirements

Date Format Requirements - Dates must be in YYYY-MM-DD format - endDate must be greater than or equal to startDate - Maximum date range may be limited depending on your plan

Error Handling

import { ChainPatrolClientError } from "@chainpatrol/sdk";

try {
  const result = await client.asset.list({
    type: "URL",
    status: "BLOCKED",
    startDate: "2024-01-01",
    endDate: "2024-01-31",
  });
} catch (error) {
  if (error instanceof ChainPatrolClientError) {
    console.error("API Error:", error.message);
  } else {
    console.error("Unexpected error:", error);
  }
}

Rate Limits & Performance

Rate Limits - Paginated requests: Up to 5 requests per second - Results are paginated for large datasets - Consider caching results for frequently accessed data

Performance Tips - Use specific date ranges to limit response size - Cache results when possible to reduce API calls - Consider pagination for very large datasets

Related Resources

Related Methods

asset.check

Check individual asset threat status

asset.submit

Submit assets for threat classification

Additional Documentation

• Asset Types Guide
• Organization Management
• API Authentication