# CortexCloud — On-Chain Data & Intelligence API

CortexCloud is an agent-native, pay-per-call on-chain data API. Agents
discover, pay for, and read blockchain data over x402 (USDC on Base,
eip155:8453) — no API keys, no subscriptions. Data sources: Alchemy
(primary) + CoinGecko (prices). Supported chains: ethereum, base,
arbitrum, polygon, optimism (name or chain id).

Every paid response is evidence-backed: each fact carries its source, a
checked_at timestamp, and an explicit missing-data indicator when a value
could not be resolved. Nothing is fabricated.

## Workflow (agent-first)

1. Read this file or GET /v1/capabilities (free) — the full endpoint list,
   live prices, chains, and providers.
2. POST the endpoint — receive a 402 x402 challenge (USDC on Base).
3. Sign the payment (EIP-3009, gasless for the buyer) and resend with the
   payment-signature header. The response is returned immediately
   (short-TTL cache makes repeats cheap).

Copy-paste buyer (official x402 SDK):

    pip install "x402" eth-account httpx
    TEST_BUYER_KEY=0x... python paid_client.py   # 402 -> sign -> 200

Source: https://raw.githubusercontent.com/jonahthan433/CortexCloud/main/examples/paid_client.py
(overrides: CC_PATH, CC_BODY, CC_URL)

## Endpoints (advertised product)

- GET /v1/data/block — $0.004
- GET /v1/data/gas-oracle — $0.004
- POST /v1/aggregate/balances — $0.004
- POST /v1/aggregate/nfts — $0.004
- POST /v1/aggregate/prices — $0.004
- POST /v1/aggregate/tx-history — $0.004
- POST /v1/data/cross-chain-compare — $0.040
- POST /v1/data/nft-ownership — $0.004
- POST /v1/data/token-balances — $0.004
- POST /v1/data/token-intel — $0.030
- POST /v1/data/token-price — $0.004
- POST /v1/data/token-risk — $0.020
- POST /v1/data/tx-history — $0.004
- POST /v1/data/wallet-intel — $0.006
- POST /v1/data/whale-alerts — $0.030

Free:

- GET /v1/capabilities — Service capabilities, limits, payment terms (free).

## Flagship: token intelligence

POST /v1/data/token-intel with {"contract": "0x...", "chain": "ethereum",
"coin_id": "usd-coin"} returns in ONE call: contract deployment check
(eth_getCode), token metadata (symbol/name/decimals), spot USD price +
24h change (CoinGecko), optional age/liquidity/market-cap (only when a
coin_id is supplied — never guessed), and recent activity evidence
(latest transfer hash + block). Each fact ships as
{value, source, checked_at[, missing]}; unresolvable fields are null with
a reason. A compact risk verdict + flags summarize the evidence.

## Honesty

- Provider costs are published; CortexCloud margin is computed transparently.
- Missing data is reported as missing, never estimated silently.
- whale-alerts applies the USD floor to native-asset transfers only;
  erc20 values are raw units (call /token-price for USD).
- What is advertised is what runs: every route above is live on this
  instance.

## Discovery

- MCP server (Streamable HTTP): https://api.cortexcloud.org/mcp
- Payment manifest (x402): https://api.cortexcloud.org/.well-known/x402.json
- Bazaar discovery: https://api.cortexcloud.org/.well-known/bazaar
- OpenAPI: https://api.cortexcloud.org/openapi.json

## Reference

- GitHub: https://github.com/jonahthan433/CortexCloudAPI