Chain Check API

curl -X POST https://onchain.ounie.com/api/checks \
  -H "Authorization: Bearer chn_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "chain": "base",
    "kind": "auto"
  }'

The whole result comes back on the same request — typically in two to five seconds, since a token check batches around twenty chain reads plus two keyless HTTP lookups. There is no job to poll.

Three credentials are accepted, in this order:

• Your app key — Authorization: Bearer chn_live_…, minted at /dashboard/api-keys. Up to 5 active. Only the sha256 hash is stored; the raw token is shown once.
• The fleet master key — your ounie.com developer key (ounie_live_…), if you have turned on “Use across Ounie apps” in your Ounie settings. One key, the whole fleet.
• The shared session cookie — what the dashboard uses. Same routes, same meter.

Hosts that cannot set an Authorization header (the Ounie AI Team’s manual MCP entry, for one) can pass ?api_key=chn_live_… instead.

{
  "ok": true,
  "check": {
    "id": "…",
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "chain": "base",
    "checked": "token",              // what it resolved to
    "kind": "contract",              // eoa | eoa_delegated | contract
    "delegate": null,                // set only for eoa_delegated
    "band": "clear",                 // clear | caution | high | insufficient
    "band_meaning": "…",
    "score": 88,                     // null iff band is insufficient
    "resolved_signals": 6,
    "resolved_weight": 108,
    "token": { "name": "USD Coin", "symbol": "USDC",
               "decimals": 6, "totalSupply": "…",
               "totalSupplyFormatted": "…" },
    "proxy": { "standard": "ZeppelinOS implementation",
               "slot": "0x7050…f8c3",
               "implementation": "0x2ce6…d779" },
    "privileged_roles": [
      { "getter": "pauser()", "label": "Pauser — can halt transfers",
        "account": "0x…" }
    ],
    "signals": [
      { "id": "sanctions", "label": "Sanctions list",
        "status": "pass",            // pass | warn | fail | insufficient
        "value": 1, "weight": 34,
        "evidence": "Not present among the … addresses on the OFAC SDN list …",
        "source": "https://…" }
    ],
    "not_checked": [
      { "id": "age", "label": "Address age", "reason": "…" }
    ],
    "thin": false,
    "credits_spent": 8,
    "disclaimer": "…"
  }
}

Every signal carries its own evidence and source. That is the contract: you should be able to go and repeat any observation we made, and recompute the band yourself from the array.

Two of these are worth reading twice. upgradeable sweeps 5 standard proxy slots rather than one, because probing EIP-1967 alone reports USDC as non-upgradeable — and USDC is a proxy, with its pointer in the older ZeppelinOS slot. And privileges can never come back clean; see the next section.

This API will tell you a token has a pauser, a blacklister or a minter. It will never tell you it has none.

We probed a nonsense function selector against three things on Base. USDC reverted. WETH returned 0x. A plain wallet also returned 0x. So an empty return means “no such function” on one contract, “a catch-all fallback swallowed the call” on another, and “there is no code at this address” on a third — and real functions revert on malformed calldata, so a revert proves nothing either.

Every response carries a not_checked array. It is not a footnote: an agent that does not know what was skipped will read an absent field as a clean one, which is the difference between a signal and a lie.

score = 100 × Σ(value × weight) ÷ Σ(weight)      // resolved signals only
band  = score ≥ 75 → clear
        score ≥ 45 → caution
        otherwise  → high
        any signal with status "fail" → high, regardless of score
        too little resolved            → insufficient, score null

weights: sanctions 34, identity 16, source_verified 22, upgradeable 14, metadata 8, privileges 16, fee_on_transfer 14

The rule that matters most: a signal we could not observe leaves the denominator. It is never scored as a zero, because that would punish an address for our blind spot and would quietly change what the number means every time an upstream wobbled. A band is always a band of the signals that resolved, and resolved_signals and resolved_weight tell you how many that was.

A check is thin only when the chain would not answer at all — we observed nothing, so there is nothing to sell. It refunds in full and credits_spent is 0.

Free forever, on any rail.

GET /api/checks?limit=20&band=caution
GET /api/checks/<id>
GET /api/pricing        # public: prices, the whole signal catalogue, notChecked

Endpoint  https://onchain.ounie.com/api/mcp   (legacy SSE: /api/sse)
Auth      Authorization: Bearer chn_live_…
          …or https://onchain.ounie.com/api/mcp?api_key=chn_live_…

get_supported_signals is public and exists for a reason: an agent that does not know a field was never checked will read its absence as a pass.

Agents with no Ounie account pay in USDC on Base. The caller here is already a wallet holding USDC on Base, which makes this the one endpoint whose audience is exactly its payment method. Two gates protect the payer, and the order is deliberate.

• Before quoting. Anything wrong with the request itself — a malformed address, a failed EIP-55 checksum, an unsupported chain, a missing kind — returns a 4xx with no price in the body. You are never asked to sign an authorization for work that cannot succeed.
• Before settling. The signature is verified off-chain, the check runs, and only then does the money move. A check the chain would not answer returns 402 thin_result, and a kind: "token" request on something that is not a token returns 402 not_a_token — neither is ever settled. An on-chain settlement is final, so the refusal has to come first.

curl -X POST https://onchain.ounie.com/api/x402/check \
  -H "Content-Type: application/json" \
  -d '{"address":"0x8335…2913","kind":"token"}'
# → 402 { "x402Version": 1, "accepts": [{
#     "scheme": "exact", "network": "base",
#     "maxAmountRequired": "96000",
#     "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
#     "payTo": "0x…",
#     "extra": { "name": "USD Coin", "version": "2" } }] }

curl -X POST https://onchain.ounie.com/api/x402/check \
  -H "X-Payment: <base64 signed payload>" \
  -H "Content-Type: application/json" \
  -d '{"address":"0x8335…2913","kind":"token"}'

$0.060 an address, $0.096 a token contract. The network is the bare base, not a CAIP-2 id — the naming scheme selects the protocol version, and a v1 offer must use the bare name. The exact scheme is an offline EIP-3009 authorization, so the facilitator pays the gas and a wallet holding only USDC can pay.

Credits are shared across every Ounie app and bought at ounie.com/dashboard/settings.