POST /screen/address/batch

Checks a list of crypto addresses in a single call: up to 500 addresses, settled with one x402 payment for the whole batch. Each item runs through the same engine as GET /screen/address — OFAC SDN and Consolidated and the EU financial sanctions list, each hit carrying the designated entity, its programmes and its designation date.

One settlement for N addresses fits the job it exists for: a payout run, a sweep, or re-checking a wallet book after a lists update.

The batch is settled as one x402 payment for the whole call and priced per address by the gateway (the first address is roughly the price of the single call, then each additional address adds to the total) — see the live /catalog for the authoritative price.

x402 golden rule: the agent pays for the answer to its question. A well-formed batch is a successful answer → 200, even when some of its items are unrecognizable (each flagged at its position) or sanctioned (each with its own verdict). The 4xx range is reserved for requests the service cannot answer — missing or malformed body, empty list, batch over the cap. Those are never charged.

Scope and limits

Same as the single call: only addresses the lists publish themselves, no derived or associated addresses, no transaction analysis, no clustering, no risk score, and absence from a list is not a safety signal. See GET /screen/address.

Request

POST with a JSON body. Set Content-Type: application/json.

POST /screen/address/batch
Content-Type: application/json

{
  "items": [
    { "address": "0x0330070FD38Ec3bB94F58FA55D40368271E9e54A" },
    { "address": "3My1ffQr5qQzmq4aBFgRqwRYqfB5zPAt8t", "chain": "bitcoin" }
  ]
}

Each item takes an address and an optional chain, which is law for that item exactly as in the single call: an address that does not have the declared family’s shape is flagged at its position, never reinterpreted as another family.

200 response — UnifiedResponse

{
  "data": {
    "count": 5,
    "summary": { "sanctioned": 2, "not_listed": 1, "error": 2 },
    "results": [ ... ],
    "lists_screened": [
      { "list": "EU-FSF", "addresses": 7 },
      { "list": "OFAC-CONS", "addresses": 0 },
      { "list": "OFAC-SDN", "addresses": 961 },
      { "list": "UN", "addresses": 0 }
    ],
    "limits": "Screening covers the designation lists and snapshot date reported above… "
  },
  "provenance": {
    "source": "ofac-sdn+ofac-consolidated+eu-fsf+un-sc",
    "fetched_at": "2026-07-30T17:49:11Z",
    "freshness": { "kind": "snapshot", "as_of": "2026-07-28T00:00:00Z" }
  }
}

lists_screened, limits and provenance are stated once for the batch: every address was screened against the same snapshot in the same call.

A successful item

Same shape as the single call’s data, minus the batch-level fields, plus its index: query, verdict, hits.

{
  "index": 1,
  "query": {
    "address": "3My1ffQr5qQzmq4aBFgRqwRYqfB5zPAt8t",
    "address_normalized": "3My1ffQr5qQzmq4aBFgRqwRYqfB5zPAt8t",
    "chain_family": "bitcoin",
    "chain_family_source": "provided"
  },
  "verdict": "sanctioned",
  "hits": [
    {
      "entity_id": "EU:EU.12747.39",
      "entity_name": "Garantex",
      "list_source": "EU-FSF",
      "programs": ["UKR"],
      "listed_on": "2025-02-24",
      "chain": "BTC",
      "address_published": "3My1ffQr5qQzmq4aBFgRqwRYqfB5zPAt8t"
    }
  ]
}

A malformed item

Flagged at its position, without failing the batch. The codes are the single endpoint’s: MISSING_PARAMETER, INVALID_INPUT, UNRECOGNIZED_ADDRESS_FORMAT.

{
  "index": 3,
  "error": "parameter 'address' is not a recognizable cryptocurrency address",
  "code": "UNRECOGNIZED_ADDRESS_FORMAT"
}

Full example

The body

{
  "items": [
    { "address": "0x0330070FD38Ec3bB94F58FA55D40368271E9e54A" },
    { "address": "3My1ffQr5qQzmq4aBFgRqwRYqfB5zPAt8t", "chain": "bitcoin" },
    { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
    { "address": "hunter2" },
    { "address": "" }
  ]
}

returns count: 5 and summary: { "sanctioned": 2, "not_listed": 1, "error": 2 } — the DPRK-designated EVM address and the Garantex Bitcoin address sanctioned, one EVM address not_listed, then UNRECOGNIZED_ADDRESS_FORMAT at index 3 and MISSING_PARAMETER at index 4.

Errors

{ "error": "batch too large: at most 500 addresses are allowed per request", "code": "BATCH_TOO_LARGE" }

See also

• GET /screen/address — the single call, with the full field reference and the chain-is-law rule.
• POST /screen/entity/batch — the same batch shape for company and person names.
• For agents — discovery surfaces, the live /catalog and how settlement works.