Search & Filtering Guide

Search is unified across entity types — there is no separate endpoint per entity. This guide shows how to query the search endpoints, filter list endpoints, and paginate large result sets using the REST API v2.

Base URL: https://xdcscan.io/api/v2

Unified search

GET /api/v2/search?q={query}

A single query matches addresses, token names and symbols, transaction hashes, and block numbers:

curl "https://xdcscan.io/api/v2/search?q=usdc"

{
  "items": [
    {
      "type": "token",
      "name": "USD Coin",
      "symbol": "USDC",
      "address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
      "token_type": "ERC-20",
      "is_verified_via_admin_panel": true
    }
  ],
  "next_page_params": null
}

Result type is one of token, address, transaction, block, or contract, so a single search box can route users to the right explorer page.

Quick search (autocomplete)

GET /api/v2/search/quick?q={query}

A lighter variant for typeahead widgets — returns at most 50 compact matches with minimal fields:

curl "https://xdcscan.io/api/v2/search/quick?q=0x1234"

Filtering transactions by method

GET /api/v2/transactions?filter={status}
GET /api/v2/addresses/{hash}/transactions?filter={direction}

On /api/v2/transactions, use filter=pending or filter=error to list only pending or failed transactions.
On address transaction lists, use filter=to, filter=from, or filter=to%20%7C%20from to restrict direction.

curl "https://xdcscan.io/api/v2/transactions?filter=pending"

To find calls to a specific contract method, fetch the address’s transactions and match method (the decoded function name) in the response items:

const res = await fetch(
  "https://xdcscan.io/api/v2/addresses/0xabcdefabcdefabcdefabcdefabcdefabcdefabcd/transactions",
);
const { items } = await res.json();
const transfers = items.filter((tx) => tx.method === "transfer");

Pagination with next_page_params

List endpoints return up to 50 items per page. When more results exist, the response includes a next_page_params object. Append its keys to the next request verbatim:

async function* fetchAll(url) {
  let next = null;
  do {
    const full = next ? url + "&" + new URLSearchParams(next).toString() : url;
    const res = await fetch(full);
    const page = await res.json();
    yield page.items;
    next = page.next_page_params;
  } while (next);
}

// Stream every ERC-20 transfer for an address
for await (const items of fetchAll(
  "https://xdcscan.io/api/v2/addresses/0x1234567890abcdef1234567890abcdef12345678/token-transfers?type=ERC-20",
)) {
  console.log(items.length, "transfers");
}

Guidelines:

Never construct page cursors yourself — the keys inside next_page_params vary per endpoint.
Stop when next_page_params is null.
Add a small delay between pages to stay within the fair-use rate limit.

Time ranges

Most list endpoints are ordered newest-first and do not take from/to timestamps. To bound a crawl by time, paginate until timestamp on the last item predates your window, then stop.

Unified search

Quick search (autocomplete)

Filtering transactions by method

Pagination with next_page_params

Time ranges

Next steps