# x402 Entity-ID Resolver

> Paid HTTP endpoint. Give it one ambiguous name or ticker ("Apple", "ETH", "Stripe") and get
> ranked candidates carrying verified canonical IDs across registries: SEC CIK + ticker, GLEIF
> LEI, Wikidata QID, CoinGecko slug. Each ID is pulled live from the entity's own official
> registry and tagged with the sources that agreed — exact, cross-registry IDs an LLM cannot
> produce reliably from memory.

Canonical endpoint: https://entityresolver.xyz/resolve

## Endpoints
- GET https://entityresolver.xyz/resolve?q=<name|ticker> — 0.005 USDC per call via x402. Returns ranked canonical-ID candidates.
- GET https://entityresolver.xyz/health — free. Service + network status.
- GET https://entityresolver.xyz/openapi.json — free. OpenAPI 3.1 schema.

## When to call (decision criteria for an agent)
Call when you need the *exact, verifiable* canonical ID(s) for an entity and must not guess:
- Disambiguating a company/asset name before a lookup in another system.
- Cross-referencing one entity across SEC / GLEIF / Wikidata / CoinGecko.
- Verifying an ID before you act on it (don't trust a recalled CIK/LEI).
Do NOT call for attributes, prices, or news — this returns identifiers, not data.

## Input
q (string, required) — one ambiguous entity name or ticker. e.g. "Apple", "AAPL", "ETH", "Stripe".

## Output (application/json)
Ranked candidates, highest confidence first:
{
  "query": "apple",
  "resolvedAt": "2026-06-06T12:00:00.000Z",
  "candidates": [
    {
      "kind": "company",
      "name": "Apple Inc.",
      "confidence": 0.98,
      "sources": ["sec", "gleif", "wikidata"],
      "ids": { "cik": "0000320193", "ticker": "AAPL", "lei": "HWUPKR0MPOU8FGXBT394", "wikidata": "Q312" }
    }
  ]
}
Fields: kind is one of company | crypto_asset | entity; confidence 0..1; sources = registries that
agreed; ids = whichever of cik/ticker/lei/wikidata/coingecko/chainId/contract/domain apply.

## Payment (x402 — no account, no API key)
Unpaid GET /resolve returns HTTP 402 with terms in the PAYMENT-REQUIRED header (body is {}).
Pay by signing an EIP-3009 USDC transfer inline (gasless for the buyer); a facilitator verifies
+ settles on Base. Terms:
- scheme:  exact
- network: eip155:8453   (Base mainnet)
- asset:   0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913   (USDC, 6 decimals)
- amount:  5000   (atomic units = 0.005 USDC)
- payTo:   service receiving wallet (carried in the 402 terms)
Use an x402 v2 client (@x402/fetch) or any 402-auto-paying tool (e.g. agentcash).

## Example
1. See terms:    curl -i "https://entityresolver.xyz/resolve?q=apple"            # HTTP 402 + PAYMENT-REQUIRED header
2. Pay + fetch:  npx agentcash fetch "https://entityresolver.xyz/resolve?q=apple" -m GET