asset.list

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

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`);

const result = await client.asset.list({
  type: "ADDRESS",
  status: "BLOCKED",
  startDate: "2024-01-01",
  endDate: "2024-01-31",
  organizationSlug: "ethereum-foundation",
});

result.assets.forEach(asset => {
  console.log(`Blocked address: ${asset.content}`);
  console.log(`Updated: ${asset.updatedAt}`);
});

{
  "assets": [
    {
      "type": "URL",
      "content": "phishing-site.com",
      "status": "BLOCKED",
      "updatedAt": "2023-06-15T10:30:00.000Z"
    },
    {
      "type": "URL",
      "content": "scam-airdrop.net",
      "status": "BLOCKED",
      "updatedAt": "2023-06-14T15:45:00.000Z"
    }
  ]
}

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

API Reference

Method Signature

Parameters

Returns

Filtering Options

By Asset Type

By Status

By Date Range

By Organization

Getting Started

Quick Start

Basic Usage Patterns

Implementation Guide

Use Cases & Patterns

Bulk Analysis

Data Export & Processing

Technical Details

Format Requirements

Error Handling

Rate Limits & Performance

asset.check

asset.submit

Additional Documentation

​API Reference

​Method Signature

​Parameters

​Returns

​Filtering Options

By Asset Type

By Status

By Date Range

By Organization

​Getting Started

​Quick Start

​Basic Usage Patterns

​Implementation Guide

​Use Cases & Patterns

​Bulk Analysis

​Data Export & Processing

​Technical Details

​Format Requirements

​Error Handling

​Rate Limits & Performance

​Related Resources

​Related Methods

asset.check

asset.submit

​Additional Documentation

API Reference

Method Signature

Parameters

Returns

Filtering Options

Getting Started

Quick Start

Basic Usage Patterns

Implementation Guide

Use Cases & Patterns

Bulk Analysis

Data Export & Processing

Technical Details

Format Requirements

Error Handling

Rate Limits & Performance

Related Resources

Related Methods

Additional Documentation