# ChainState

One-call Base address profile for agents: code, proxy, interfaces, token, balances, denylist.

ChainState answers everything an agent needs to know about a Base address before interacting with it, in one paid call rather than four to six a-la-carte lookups. It reports whether the address holds code and how much, resolves proxies across all seven known slot layouts — including the legacy OpenZeppelin slot that Base USDC really uses, which an EIP-1967-only detector misses entirely — and returns the implementation behind the indirection, ERC-165 interface support, behavioural ERC-20 detection, token metadata, and the balances you asked for. There is no model anywhere in it. A contract that does not answer supportsInterface is reported as null, never false, and there is deliberately no reverse-name field: a name the subject can set for itself, published without a forward check, would be the one spoofable value in the response.

## Payment

- Protocol: x402 V2, scheme `exact`, network `eip155:8453` (Base mainnet)
- Asset: USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- No accounts, no API keys, no subscriptions.
- Failed calls are not charged. Only a successful, usable result settles.
- Payment authorization window: 60s

## Endpoints

### `POST /v1/chain/state` — $0.01 per successful call

Profile a Base address in one call instead of four to six lookups. Returns contract or externally owned plus code size, proxy detection across all seven slot layouts including the legacy OpenZeppelin slot Base USDC uses, the resolved implementation, ERC-165 and behavioural ERC-20 detection, token metadata, requested ERC-20 balances, and denylist hits. Answers unknown rather than guessing, and null rather than false when a contract stays silent. Not a guarantee that an address is safe.

Unpaid request returns HTTP 402 with the challenge in the `PAYMENT-REQUIRED` header:

```bash
curl -i -sS -X POST https://chainstate.schemasure.com/v1/chain/state \
  -H 'content-type: application/json' \
  -d '{"address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}'
```

Example successful response:

```json
{
  "ok": true,
  "verdict": "warn",
  "confidence": 1,
  "risk_codes": [
    "PROXY_UPGRADEABLE"
  ],
  "evidence": [
    {
      "code": "INTERFACE_PROBE_UNANSWERED",
      "severity": "info",
      "detail": "This contract did not answer supportsInterface, so ERC-721 and ERC-1155 support is reported as null. That is not evidence against them: plenty of live contracts predate ERC-165 entirely.",
      "source": "erc165"
    },
    {
      "code": "PROXY_UPGRADEABLE",
      "severity": "medium",
      "detail": "This is an upgradeable zeppelinos proxy. Everything reported here describes the implementation deployed right now; the admin can point it elsewhere before your next call lands, so this is a risk signal rather than metadata.",
      "source": "proxy-slots",
      "data": {
        "kind": "zeppelinos",
        "implementation": "0x2Ce6311ddAE708829bc0784C967b7d77D19FD779",
        "admin": "0x4fc7850364958d97B4d3f5A08f79db2493f8cA44"
      }
    }
  ],
  "result": {
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "chain": "eip155:8453",
    "account": {
      "is_contract": true,
      "code_size": 1852,
      "detail": "1852 bytes of runtime code"
    },
    "proxy": {
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "kind": "zeppelinos",
      "implementation": "0x2Ce6311ddAE708829bc0784C967b7d77D19FD779",
      "admin": "0x4fc7850364958d97B4d3f5A08f79db2493f8cA44",
      "beacon": null,
      "upgradeable": true,
      "slots_probed": [
        {
          "slot": "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc",
          "label": "eip1967.implementation",
          "value": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "address": null
        },
        {
          "slot": "0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103",
          "label": "eip1967.admin",
          "value": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "address": null
        },
        {
          "slot": "0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50",
          "label": "eip1967.beacon",
          "value": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "address": null
        },
        {
          "slot": "0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7",
          "label": "eip1822.uups",
          "value": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "address": null
        },
        {
          "slot": "0x7050c9e0f4ca769c69bd3a8ef740bc37934f8e2c036e5a723fd8ee048ed3f8c3",
          "label": "zeppelinos.implementation",
          "value": "0x0000000000000000000000002ce6311ddae708829bc0784c967b7d77d19fd779",
          "address": "0x2Ce6311ddAE708829bc0784C967b7d77D19FD779"
        },
        {
          "slot": "0x10d6a54a4754c8869d6886b5f5d7fbfa5b4522237ea5c60d11bc4e7a1ff9390b",
          "label": "zeppelinos.admin",
          "value": "0x0000000000000000000000004fc7850364958d97b4d3f5a08f79db2493f8ca44",
          "address": "0x4fc7850364958d97B4d3f5A08f79db2493f8cA44"
        },
        {
          "slot": "0xc8fcad8db84d3cc18b4c41d551ea0ee66dd599cde068d998e57d5e09332c131c",
          "label": "eip2535.diamond",
          "value": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "address": null
        }
      ],
      "detail": "resolved through the legacy zeppelinos slot; the EIP-1967 slot is empty on this contract, which is the case for Base USDC"
    },
    "interfaces": {
      "erc165": null,
      "erc721": null,
      "erc1155": null,
      "erc20": true,
      "detail": "supportsInterface did not answer, so ERC-721 and ERC-1155 are reported as unknown rather than absent; ERC-20 is confirmed behaviourally from totalSupply, decimals, and balanceOf"
    },
    "token": {
      "symbol": "USDC",
      "decimals": 6,
      "total_supply": "4305008625389354",
      "detail": "symbol, decimals, and totalSupply read from the token"
    },
    "balances": [],
    "denylist_hits": [],
    "unresolved": [
      "ERC-165 interface support: supportsInterface did not answer"
    ],
    "rpc": {
      "configured": true,
      "reachable": true,
      "endpoints": [
        {
          "url": "https://mainnet.base.org",
          "latest": true,
          "archive": true,
          "simulate": true
        }
      ]
    }
  },
  "policy_version": "2026-09-19",
  "request_hash": "sha256:96b41fa639c553a6dc6bfaa1d8ccc056912abc36e8bbde3d65f3e1edc2bd147f",
  "data_versions": {
    "denylist": "2026-08-03.1",
    "abi_packs": "2026-08-03.1",
    "proxy_slots": "7",
    "policy": "2026-09-19",
    "chain": "eip155:8453"
  },
  "warnings": []
}
```

## Result contract

Every response is the shared portfolio envelope: `ok`, `verdict`, `confidence`, `risk_codes`,
`evidence`, `result`, `policy_version`, `request_hash`, `data_versions`, `warnings`.

`verdict: "unknown"` is a real answer, not a failure. It means the service could not determine
the result and says why in `evidence`. It is never silently reported as a safe or clean outcome.

## Service level

- Target P50: 600 ms
- Target P95: 2000 ms

## Data handling

- Caller content is processed transiently and never retained.
- No training on customer content.
- Subprocessors: base-rpc.publicnode.com, base.gateway.tenderly.co, mainnet.base.org

## Machine-readable surfaces

- https://chainstate.schemasure.com/openapi.json
- https://chainstate.schemasure.com/.well-known/x402.json
- https://chainstate.schemasure.com/.well-known/pricing.json
- https://chainstate.schemasure.com/.well-known/benchmarks.json
- https://chainstate.schemasure.com/.well-known/data-handling.json
- https://chainstate.schemasure.com/apis.json
- https://chainstate.schemasure.com/SKILL.md