Docs

Quick Start

1. Choose one priced API. Invalid JSON returns VALIDATION_ERROR and does not ask for payment.
2. POST the same JSON without PAYMENT-SIGNATURE. The server returns HTTP 402 and a PAYMENT-REQUIRED header. The JSON body is only the error and does not contain the query result.
3. Read x402Version 2 and the single accepts entry. Pay that exact Base USDC amount, asset, network, and receiving address.
4. Repeat the same request with the x402 v2 PAYMENT-SIGNATURE header. The server checks it against the challenge, verifies it, runs the query, and settles only after the query succeeds.
5. The result is returned only after settlement is confirmed, with a PAYMENT-RESPONSE header. Sending that same authorization again returns the stored result and does not run the query or settlement again.

A timeout or an unconfirmed settlement returns PAYMENT_SETTLEMENT_UNKNOWN. That response is not success, and the server does not retry settlement.

Payment

The PAYMENT-REQUIRED challenge is x402 v2. Its accepts values come from the server, not from the client.

• Scheme: exact
• Network: eip155:8453
• Asset: 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
• Pay to: 0xa0679946b8f74c778566b5250a345932259be0c4
• Maximum timeout: 60 seconds
• EIP-712 extra: USD Coin, version 2

• Transaction Status, Base: 0.001 USDC (1000 atomic units) at POST /api/base/transaction-status
• Wallet Balance, Base: 0.002 USDC (2000 atomic units) at POST /api/base/wallet-balance
• Gas Estimate, Base: 0.002 USDC (2000 atomic units) at POST /api/base/gas-estimate
• Transaction Status, Multi-chain: 0.001 USDC (1000 atomic units) at POST /api/v1/transaction-status
• Wallet Balance, Multi-chain: 0.002 USDC (2000 atomic units) at POST /api/v1/wallet-balance
• Gas Estimate, Multi-chain: 0.002 USDC (2000 atomic units) at POST /api/v1/gas-estimate
• Token Price, Multi-chain: 0.001 USDC (1000 atomic units) at POST /api/v1/token-price
• Token Holder Count History, Multi-chain: 0.002 USDC (2000 atomic units) at POST /api/v1/token-holder-count-history
• Token Security, Base: 0.001 USDC (1000 atomic units) at POST /api/base/token-risk
• Honeypot Detection, Multi-chain: 0.001 USDC (1000 atomic units) at POST /api/v1/honeypot-detection
• DEX Pool Liquidity, Multi-chain: 0.001 USDC (1000 atomic units) at POST /api/v1/dex-pool-liquidity
• DEX Pool Discovery, Multi-chain: 0.001 USDC (1000 atomic units) at POST /api/v1/dex-pool-discovery
• DEX OHLCV, Multi-chain: 0.001 USDC (1000 atomic units) at POST /api/v1/dex-ohlcv
• Web Search, Web: 0.01 USDC (10000 atomic units) at POST /api/v1/web-search
• Web Page Scraping, Web: 0.01 USDC (10000 atomic units) at POST /api/v1/web-page-scraping
• Web Content Extraction, Web: 0.01 USDC (10000 atomic units) at POST /api/v1/web-content-extraction
• Web Search & Answer, Web: 0.01 USDC (10000 atomic units) at POST /api/v1/web-search-answer
• Text Summarization, AI: 0.002 USDC (2000 atomic units) standard, or 0.006 USDC (6000 atomic units) large at POST /api/v1/text-summarization
• Structured Extraction, AI: 0.002 USDC (2000 atomic units) standard, or 0.006 USDC (6000 atomic units) large at POST /api/v1/structured-extraction
• Text Classification, AI: 0.002 USDC (2000 atomic units) at POST /api/v1/text-classification

Headers are PAYMENT-REQUIRED on the challenge, PAYMENT-SIGNATURE on the paid request, and PAYMENT-RESPONSE on a confirmed result. A signature longer than 8192 characters is rejected before it is decoded.

{
  "ok": false,
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Payment required",
    "details": []
  }
}

API Reference

Choose one route. Each endpoint keeps its own price, query networks, and payment challenge.

Transaction Status, Base

POST /api/base/transaction-status costs 0.001 USDC (1000 atomic units). Returns the status of one Base transaction.

Query networks: base (eip155:8453). An agent checks whether a transaction succeeded, is still pending, or was not found.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• hash, required. 0x-prefixed 32-byte transaction hash.

Output

The response is { ok, service, data }. data.status is not_found, pending, success, or failed. blockNumber and gasUsed are decimal strings or null. The hash is lowercase.

{
  "hash": "0x1111111111111111111111111111111111111111111111111111111111111111"
}

{
  "ok": true,
  "service": "base.transactionStatus",
  "data": {
    "network": "eip155:8453",
    "hash": "0x1111111111111111111111111111111111111111111111111111111111111111",
    "status": "success",
    "blockNumber": "16",
    "gasUsed": "21000"
  }
}

Wallet Balance, Base

POST /api/base/wallet-balance costs 0.002 USDC (2000 atomic units). Returns Base ETH and up to five token balances.

Query networks: base (eip155:8453). An agent reads the native balance and up to five token balances for one wallet.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• address, required. 0x-prefixed 20-byte wallet address.
• tokens, optional. Optional ERC-20 addresses, at most five.

Output

data.balances always includes the native ETH balance. A readable token adds an erc20 entry whose raw value is set. symbol, decimals, and amount stay null on that entry; the null metadata is the documented result, not a failed call. A token that cannot be read sets error to unavailable and raw to null.

{
  "address": "0x2222222222222222222222222222222222222222",
  "tokens": [
    "0x3333333333333333333333333333333333333333"
  ]
}

{
  "ok": true,
  "service": "base.walletBalance",
  "data": {
    "network": "eip155:8453",
    "address": "0x2222222222222222222222222222222222222222",
    "balances": [
      {
        "kind": "native",
        "symbol": "ETH",
        "contract": null,
        "raw": "0",
        "decimals": 18,
        "amount": "0"
      },
      {
        "kind": "erc20",
        "symbol": null,
        "contract": "0x3333333333333333333333333333333333333333",
        "raw": "0",
        "decimals": null,
        "amount": null
      }
    ]
  }
}

Gas Estimate, Base

POST /api/base/gas-estimate costs 0.002 USDC (2000 atomic units). Returns a Base gas estimate and fee suggestion.

Query networks: base (eip155:8453). An agent estimates gas and EIP-1559 fees before sending a transaction.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• from, optional. Optional 0x-prefixed 20-byte address.
• to, provide to or data. 0x-prefixed 20-byte address. Provide to or data.
• value, optional. Hex quantity.
• data, provide to or data. Even-length hex, at most 4096 bytes. Provide to or data.

Output

data.gas and the three data.fees values are decimal strings. fees contains baseFeePerGas, maxPriorityFeePerGas, and maxFeePerGas.

{
  "to": "0x2222222222222222222222222222222222222222",
  "data": "0x"
}

{
  "ok": true,
  "service": "base.gasEstimate",
  "data": {
    "network": "eip155:8453",
    "gas": "21000",
    "fees": {
      "baseFeePerGas": "1",
      "maxPriorityFeePerGas": "1",
      "maxFeePerGas": "2"
    }
  }
}

Transaction Status, Multi-chain

POST /api/v1/transaction-status costs 0.001 USDC (1000 atomic units). Returns one transaction status on Ethereum, Base, BNB Smart Chain, Arbitrum, Solana, or TRON.

Query networks: ethereum (eip155:1), base (eip155:8453), bsc (eip155:56), arbitrum (eip155:42161), solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp), tron (tron:0x2b6653dc). An agent checks whether a transaction succeeded, is still pending, or was not found.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• chain, required. ethereum, base, bsc, arbitrum, tron, solana. EVM and TRON use hash. Solana uses signature.
• hash, required for its chain. EVM and TRON JSON-RPC transaction hash.
• signature, required for its chain. Solana transaction signature. Use this instead of hash.

Output

EVM and TRON return hash, status, blockNumber, and gasUsed. Solana returns signature, status, and slot. A missing Solana status uses detail absent_or_outside_retention because the provider keeps only recent history.

{
  "chain": "ethereum",
  "hash": "0x1111111111111111111111111111111111111111111111111111111111111111"
}

{
  "ok": true,
  "service": "chain.transactionStatus",
  "data": {
    "chain": "ethereum",
    "network": "eip155:1",
    "hash": "0x1111111111111111111111111111111111111111111111111111111111111111",
    "status": "success",
    "blockNumber": "16",
    "gasUsed": "21000"
  }
}

Wallet Balance, Multi-chain

POST /api/v1/wallet-balance costs 0.002 USDC (2000 atomic units). Returns the native balance and up to five token balances for one supported chain.

Query networks: ethereum (eip155:1), base (eip155:8453), bsc (eip155:56), arbitrum (eip155:42161), solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp), tron (tron:0x2b6653dc). An agent reads the native balance and up to five token balances for one wallet.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• chain, required. ethereum, base, bsc, arbitrum, solana, or tron.
• address, required. EVM and TRON JSON-RPC use a 0x address. Solana uses a base58 address. TRON base58 addresses are not accepted.
• tokens, optional. Optional token or mint addresses, at most five.

Output

The native entry uses the chain symbol and decimals. Token entries use kind token. EVM token entries can include raw while symbol, decimals, and amount stay null. Solana can include decimals and amount. error unavailable means that token balance was not read.

{
  "chain": "ethereum",
  "address": "0x2222222222222222222222222222222222222222",
  "tokens": [
    "0x3333333333333333333333333333333333333333"
  ]
}

{
  "ok": true,
  "service": "chain.walletBalance",
  "data": {
    "chain": "ethereum",
    "network": "eip155:1",
    "address": "0x2222222222222222222222222222222222222222",
    "balances": [
      {
        "kind": "native",
        "symbol": "ETH",
        "contract": null,
        "raw": "0",
        "decimals": 18,
        "amount": "0"
      }
    ]
  }
}

Gas Estimate, Multi-chain

POST /api/v1/gas-estimate costs 0.002 USDC (2000 atomic units). Returns an EIP-1559 gas estimate on Ethereum, Base, or Arbitrum. BNB Smart Chain, Solana, and TRON are unsupported.

Query networks: ethereum (eip155:1), base (eip155:8453), arbitrum (eip155:42161). An agent estimates gas and EIP-1559 fees before sending a transaction.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• chain, required. ethereum, base, arbitrum.
• from, optional. Optional 0x-prefixed 20-byte address.
• to, provide to or data. 0x-prefixed 20-byte address. Provide to or data.
• value, optional. Hex quantity.
• data, provide to or data. Even-length hex, at most 4096 bytes. Provide to or data.

Output

Only Ethereum, Base, and Arbitrum are accepted. The fee fields are EIP-1559 values. BNB Smart Chain, Solana, and TRON return a validation error and are not charged.

{
  "chain": "ethereum",
  "to": "0x2222222222222222222222222222222222222222",
  "data": "0x"
}

{
  "ok": true,
  "service": "chain.gasEstimate",
  "data": {
    "chain": "ethereum",
    "network": "eip155:1",
    "gas": "21000",
    "fees": {
      "baseFeePerGas": "1",
      "maxPriorityFeePerGas": "1",
      "maxFeePerGas": "2"
    }
  }
}

Token Price, Multi-chain

POST /api/v1/token-price costs 0.001 USDC (1000 atomic units). Returns the provider USD price string for one token on Ethereum, Base, BNB Smart Chain, or Arbitrum. Omit the contract for the native coin.

Query networks: ethereum (eip155:1), base (eip155:8453), bsc (eip155:56), arbitrum (eip155:42161). An agent reads the provider USD price string for one token, or for the chain native coin when the contract is omitted.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• chain, required. ethereum, base, bsc, or arbitrum.
• contractAddress, optional. Optional 0x contract address. Omit it to price the chain native coin.

Output

data.usdPrice is the provider string, unchanged. contractAddress is null when the request omits it. Payment remains Base USDC for every query chain.

{
  "chain": "ethereum",
  "contractAddress": "0x3333333333333333333333333333333333333333"
}

{
  "ok": true,
  "service": "chain.tokenPrice",
  "data": {
    "chain": "ethereum",
    "network": "eip155:1",
    "blockchain": "eth",
    "contractAddress": "0x3333333333333333333333333333333333333333",
    "usdPrice": "0.031240514621682378"
  }
}

Token Holder Count History, Multi-chain

POST /api/v1/token-holder-count-history costs 0.002 USDC (2000 atomic units). Returns the validated holder-count page for one token on Ethereum, Base, BNB Smart Chain, or Arbitrum. pageSize is the requested target. The delivered page may be larger and has at most 10 rows.

Query networks: ethereum (eip155:1), base (eip155:8453), bsc (eip155:56), arbitrum (eip155:42161). An agent reads the validated holder-count page in provider order. pageSize is the requested target. The page may contain more rows than requested and at most 10.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• chain, required. ethereum, base, bsc, or arbitrum.
• contractAddress, required. 0x-prefixed 20-byte token contract address.
• pageSize, optional. Optional integer from 1 to 10. The default is 10. It is the target count sent to the provider, not a strict output limit.

Output

data.holderCountHistory keeps the provider row order and each lastUpdatedAt value. pageSize is the target requested from the provider, not a strict output count. The route delivers every validated row from that page. The page may contain more rows than pageSize and contains at most 10. The route rejects caller pageToken. It does not define a sort, a daily interval, or a current holder total.

{
  "chain": "ethereum",
  "contractAddress": "0x3333333333333333333333333333333333333333",
  "pageSize": 10
}

{
  "ok": true,
  "service": "chain.tokenHolderCountHistory",
  "data": {
    "chain": "ethereum",
    "network": "eip155:1",
    "blockchain": "eth",
    "contractAddress": "0x3333333333333333333333333333333333333333",
    "tokenDecimals": 6,
    "holderCountHistory": [
      {
        "holderCount": 4498953,
        "lastUpdatedAt": "2022-07-29T05:41:21Z",
        "totalAmount": "36819785005.419766",
        "totalAmountRawInteger": "36819785005419766"
      }
    ]
  }
}

Token Security, Base

POST /api/base/token-risk costs 0.001 USDC (1000 atomic units). Returns Base token security flags for one token address. States are flagged, not_indicated, or unknown. Tax rates stay provider strings.

Query networks: base (eip155:8453). An agent reads Base token security flags for one address. Missing flags stay unknown. Tax rates stay provider strings.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• address, required. 0x-prefixed 20-byte token address on Base.

Output

data.network is eip155:8453 and data.address is lowercase. data.signals contains the fixed flag set. Each state is flagged, not_indicated, or unknown. buyTax, sellTax, and transferTax keep the provider string in raw. Liquidity pools, provider JSON, and warning text are omitted. Invalid input is HTTP 400 before payment. A valid unpaid call is HTTP 402. Upstream failure, HTTP 429, timeout, and invalid provider data are not settled.

{
  "address": "0x3333333333333333333333333333333333333333"
}

{
  "ok": true,
  "service": "base.tokenRisk",
  "data": {
    "network": "eip155:8453",
    "address": "0x3333333333333333333333333333333333333333",
    "signals": {
      "honeypot": {
        "state": "flagged",
        "basis": "upstream"
      },
      "proxy": {
        "state": "unknown",
        "basis": "upstream"
      },
      "mintable": {
        "state": "unknown",
        "basis": "upstream"
      },
      "ownerChangeBalance": {
        "state": "unknown",
        "basis": "upstream"
      },
      "hiddenOwner": {
        "state": "unknown",
        "basis": "upstream"
      },
      "canTakeBackOwnership": {
        "state": "unknown",
        "basis": "upstream"
      },
      "selfdestruct": {
        "state": "unknown",
        "basis": "upstream"
      },
      "externalCall": {
        "state": "unknown",
        "basis": "upstream"
      },
      "transferPausable": {
        "state": "unknown",
        "basis": "upstream"
      },
      "blacklist": {
        "state": "unknown",
        "basis": "upstream"
      },
      "whitelist": {
        "state": "unknown",
        "basis": "upstream"
      },
      "taxModifiable": {
        "state": "unknown",
        "basis": "upstream"
      },
      "personalTaxModifiable": {
        "state": "unknown",
        "basis": "upstream"
      },
      "cannotBuy": {
        "state": "unknown",
        "basis": "upstream"
      },
      "cannotSellAll": {
        "state": "unknown",
        "basis": "upstream"
      },
      "tradingCooldown": {
        "state": "unknown",
        "basis": "upstream"
      },
      "antiWhale": {
        "state": "unknown",
        "basis": "upstream"
      },
      "antiWhaleModifiable": {
        "state": "unknown",
        "basis": "upstream"
      },
      "gasAbuse": {
        "state": "unknown",
        "basis": "upstream"
      },
      "airdropScam": {
        "state": "unknown",
        "basis": "upstream"
      },
      "closedSource": {
        "state": "unknown",
        "basis": "upstream"
      },
      "fakeToken": {
        "state": "unknown",
        "basis": "upstream"
      },
      "buyTax": {
        "state": "flagged",
        "basis": "upstream",
        "raw": "0.05"
      },
      "sellTax": {
        "state": "not_indicated",
        "basis": "upstream",
        "raw": "0"
      },
      "transferTax": {
        "state": "unknown",
        "basis": "upstream",
        "raw": null
      }
    }
  }
}

Honeypot Detection, Multi-chain

POST /api/v1/honeypot-detection costs 0.001 USDC (1000 atomic units). Returns a honeypot check for one token on Ethereum, Base, or BNB Smart Chain. Simulation and honeypot stay separate. Unknown is not safe.

Query networks: ethereum (eip155:1), base (eip155:8453), bsc (eip155:56). An agent reads one honeypot simulation. Simulation and honeypot stay separate. Unknown is not a safe result. Tax literals stay unchanged.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• chain, required. ethereum, base, or bsc.
• address, required. 0x-prefixed 20-byte address.

Output

data.chain is ethereum, base, or bsc, and data.network is the matching eip155 network. data.address is the requested lowercase address. simulation is simulated, not_simulated, or unknown. honeypot.state is flagged, not_indicated, or unknown. basis is simulation, other, or null. Taxes are read only after a successful simulation, and raw keeps the provider JSON number literal. A failed simulation with a honeypot boolean is delivered and its taxes stay unknown. Unknown is not a safe result. Pair data and provider JSON are omitted. Invalid input is HTTP 400 before payment. A valid unpaid call is HTTP 402. Upstream failure, timeout, a chain id mismatch, and invalid provider data are not settled.

{
  "chain": "ethereum",
  "address": "0x3333333333333333333333333333333333333333"
}

{
  "ok": true,
  "service": "chain.honeypotDetection",
  "data": {
    "chain": "ethereum",
    "network": "eip155:1",
    "address": "0x3333333333333333333333333333333333333333",
    "simulation": "simulated",
    "honeypot": {
      "state": "flagged",
      "basis": "simulation"
    },
    "buyTax": {
      "state": "not_indicated",
      "raw": "0"
    },
    "sellTax": {
      "state": "flagged",
      "raw": "1.5"
    },
    "transferTax": {
      "state": "unknown",
      "raw": null
    }
  }
}

DEX Pool Liquidity, Multi-chain

POST /api/v1/dex-pool-liquidity costs 0.001 USDC (1000 atomic units). Returns the provider reserve string for one DEX pool on Ethereum, Base, or BNB Smart Chain. A missing reserve stays unknown.

Query networks: ethereum (eip155:1), base (eip155:8453), bsc (eip155:56). An agent reads one DEX pool reserve. The reserve stays the provider string. A missing reserve stays unknown.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• chain, required. ethereum, base, or bsc.
• pool, required. 0x-prefixed 20-byte pool address.

Output

data.chain is ethereum, base, or bsc, and data.network is the matching eip155 network. data.pool is the requested lowercase pool address. reserveUsd.raw keeps the provider reserve string. A missing or null reserve is unknown and is not returned as zero. Invalid input is HTTP 400 before payment. A valid unpaid call is HTTP 402. A missing pool, upstream failure, timeout, and invalid provider data are not settled.

{
  "chain": "base",
  "pool": "0x3333333333333333333333333333333333333333"
}

{
  "ok": true,
  "service": "chain.dexPoolLiquidity",
  "data": {
    "chain": "base",
    "network": "eip155:8453",
    "pool": "0x3333333333333333333333333333333333333333",
    "reserveUsd": {
      "state": "present",
      "raw": "13843.8176"
    }
  }
}

DEX Pool Discovery, Multi-chain

POST /api/v1/dex-pool-discovery costs 0.001 USDC (1000 atomic units). Returns one page of trending or new DEX pools on Ethereum, Base, or BNB Smart Chain. Missing values stay null.

Query networks: ethereum (eip155:1), base (eip155:8453), bsc (eip155:56). An agent reads one page of trending or new DEX pools. Missing values stay null. An empty page stays empty.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• chain, required. ethereum, base, or bsc.
• kind, required. trending or new. duration is rejected for new.
• page, optional. Page from 1 to 10. Defaults to 1.
• duration, optional. Optional for trending. Rejected for new.

Output

data.chain is ethereum, base, or bsc, and data.network is the matching eip155 network. data.kind is trending or new. data.page is an integer from 1 to 10. data.duration is the requested trending duration, or null. data.pools contains at most 20 pools. An empty provider page is delivered as an empty pools array. reserveUsd and volumeUsd24h keep the provider literal. A missing value is null and is not returned as zero. transactions24h uses an integer when the count is present and null when it is missing. Token addresses come from the included tokens. Invalid input is HTTP 400 before payment. A valid unpaid call is HTTP 402. More than 20 pools, a missing pool address, a network mismatch, invalid provider data, upstream failure, and timeout are not settled.

{
  "chain": "base",
  "kind": "trending",
  "page": 1,
  "duration": "24h"
}

{
  "ok": true,
  "service": "chain.dexPoolDiscovery",
  "data": {
    "chain": "base",
    "network": "eip155:8453",
    "kind": "trending",
    "duration": "24h",
    "page": 1,
    "pools": [
      {
        "address": "0x3333333333333333333333333333333333333333",
        "name": "USDC / WETH",
        "baseToken": "0x1111111111111111111111111111111111111111",
        "quoteToken": "0x2222222222222222222222222222222222222222",
        "reserveUsd": "13843.8176",
        "volumeUsd24h": "9007199254740993",
        "transactions24h": {
          "buys": 0,
          "sells": 2,
          "buyers": 1,
          "sellers": null
        }
      }
    ]
  }
}

DEX OHLCV, Multi-chain

POST /api/v1/dex-ohlcv costs 0.001 USDC (1000 atomic units). Returns OHLCV candles for one DEX pool on Ethereum, Base, or BNB Smart Chain. Values keep provider literals.

Query networks: ethereum (eip155:1), base (eip155:8453), bsc (eip155:56). An agent reads DEX OHLCV candles for one pool. Values stay provider literals. Missing candles are not filled.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• chain, required. ethereum, base, or bsc.
• pool, required. 0x-prefixed 20-byte pool address.
• timeframe, required. day, hour, minute, or second.
• aggregate, optional. day: 1. hour: 1, 4, 12. minute: 1, 5, 15. second: 1, 15, 30. Defaults to 1.
• limit, optional. Candle count from 1 to 100. Defaults to 100.

Output

data.chain is ethereum, base, or bsc, and data.network is the matching eip155 network. data.pool is the requested lowercase pool address. timeframe is day, hour, minute, or second. aggregate follows the official set: day 1; hour 1, 4, or 12; minute 1, 5, or 15; second 1, 15, or 30. It defaults to 1. limit is an integer from 1 to 100 and defaults to 100. Each candle keeps timestamp, open, high, low, close, and volume as the provider JSON number literals. Missing candles are not filled and unknown values are not returned as zero. An empty candle list is not delivered. Invalid input is HTTP 400 before payment. A valid unpaid call is HTTP 402. Invalid candles, more candles than limit, a result over 16384 characters, upstream failure, and timeout are not settled.

{
  "chain": "base",
  "pool": "0x3333333333333333333333333333333333333333",
  "timeframe": "hour",
  "aggregate": 4,
  "limit": 1
}

{
  "ok": true,
  "service": "chain.dexOhlcv",
  "data": {
    "chain": "base",
    "network": "eip155:8453",
    "pool": "0x3333333333333333333333333333333333333333",
    "timeframe": "hour",
    "aggregate": 4,
    "candles": [
      {
        "timestamp": "1779926400",
        "open": "1.00208165944741",
        "high": "1.00257871811779",
        "low": "0.985925654401274",
        "close": "1.00027690571219",
        "volume": "3481.679733097695"
      }
    ]
  }
}

Web Search, Web

POST /api/v1/web-search costs 0.01 USDC (10000 atomic units). Returns title, url, and content for one web search. A valid empty result list is delivered.

Query networks: public web. An agent reads web search results for one query. An empty result list can be delivered.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• query, required. Search text from 1 to 400 characters.
• maxResults, optional. Result count from 1 to 5. Defaults to 5.

Output

data.query is the requested text. data.results contains at most maxResults items, each with title, url, and content. maxResults defaults to 5 and accepts 1 to 5. A valid empty list is delivered. Invalid input, including extra fields, is HTTP 400 before payment. A valid unpaid call is HTTP 402. Invalid result items, more results than requested, a result over 16384 characters, upstream failure, and timeout are not settled and are not truncated.

{
  "query": "base usdc contract",
  "maxResults": 5
}

{
  "ok": true,
  "service": "web.search",
  "data": {
    "query": "base usdc contract",
    "results": [
      {
        "title": "USDC",
        "url": "https://example.com/usdc",
        "content": "USD Coin on Base."
      }
    ]
  }
}

Web Page Scraping, Web

POST /api/v1/web-page-scraping costs 0.01 USDC (10000 atomic units). Returns one public page as markdown. Empty or failed content is not delivered.

Query networks: public web. An agent reads one public page as markdown. Empty or failed content is not delivered.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• url, required. One public http or https URL.

Output

data.url is the requested public URL. data.content keeps the provider page text. Private, local, and metadata URLs are rejected before payment. One upstream request is sent with redirect following disabled. Empty content, a failed page, a result over 16384 characters, upstream failure, and timeout are not settled and are not truncated.

{
  "url": "https://example.com/"
}

{
  "ok": true,
  "service": "web.pageScraping",
  "data": {
    "url": "https://example.com/",
    "content": "# Example"
  }
}

Web Content Extraction, Web

POST /api/v1/web-content-extraction costs 0.01 USDC (10000 atomic units). Returns query-related text from one page. This is ranked text, not a custom JSON schema.

Query networks: public web. An agent reads query-related text from one page. The text is ranked excerpts, not a custom JSON schema.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• url, required. One public http or https URL.
• query, required. Text used to select related excerpts, from 1 to 400 characters.

Output

data.url and data.query are the requested values. data.content is ranked page text for that query. This route does not accept a custom JSON schema. Private, local, and metadata URLs are rejected before payment. Empty content, a failed page, a result over 16384 characters, upstream failure, and timeout are not settled and are not truncated.

{
  "url": "https://example.com/",
  "query": "usdc contract"
}

{
  "ok": true,
  "service": "web.contentExtraction",
  "data": {
    "url": "https://example.com/",
    "query": "usdc contract",
    "content": "USD Coin contract"
  }
}

Web Search & Answer, Web

POST /api/v1/web-search-answer costs 0.01 USDC (10000 atomic units). Returns one search answer and its source results. An empty answer is not delivered.

Query networks: public web. An agent reads one search answer and its sources from the same search call. An empty answer is not delivered.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• query, required. Question text from 1 to 400 characters.
• maxResults, optional. Source count from 1 to 5. Defaults to 5.

Output

data.query is the requested text. data.answer is the provider answer from the same search call. data.results contains the source title, url, and content. An empty answer is not delivered. A valid empty source list can be delivered with an answer. Invalid input is HTTP 400 before payment. A valid unpaid call is HTTP 402. Invalid sources, a result over 16384 characters, upstream failure, and timeout are not settled and are not truncated.

{
  "query": "what is base usdc",
  "maxResults": 5
}

{
  "ok": true,
  "service": "web.searchAnswer",
  "data": {
    "query": "what is base usdc",
    "answer": "USDC is a dollar stablecoin on Base.",
    "results": [
      {
        "title": "USDC",
        "url": "https://example.com/usdc",
        "content": "USD Coin on Base."
      }
    ]
  }
}

Text Summarization, AI

POST /api/v1/text-summarization Standard costs 0.002 USDC (2000 atomic units). Large costs 0.006 USDC (6000 atomic units) and must be requested explicitly. Summarizes one text. Standard is 0.002 USDC. Large is 0.006 USDC and must be explicit. Test price, not a formal sale price.

Query networks: text. An agent summarizes one text. Standard is the default. Large must be explicit.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• text, required. Text to summarize. The full request, including the fixed prompt and schema, must stay within the tier input ceiling.
• tier, optional. Optional. Standard is the default. Large must be explicit and uses the large price.

Output

data.tier is standard or large. data.summary is the model summary. Standard allows 2000 input tokens and 400 output tokens at 2000 atomic units. Large allows 8000 input tokens and 1200 output tokens at 6000 atomic units and must be explicit. The input ceiling includes the fixed prompt and schema. Invalid input is HTTP 400 before payment. A valid unpaid call is HTTP 402 for the tier price. Refusal, incomplete output, invalid JSON, usage over the ceiling, upstream failure, and timeout are not settled.

{
  "text": "Base USDC is a stablecoin."
}

{
  "ok": true,
  "service": "ai.summarize",
  "data": {
    "tier": "standard",
    "summary": "USDC is a dollar stablecoin on Base."
  }
}

Structured Extraction, AI

POST /api/v1/structured-extraction Standard costs 0.002 USDC (2000 atomic units). Large costs 0.006 USDC (6000 atomic units) and must be requested explicitly. Extracts one controlled name. Standard is 0.002 USDC. Large is 0.006 USDC and must be explicit. Test price, not a formal sale price.

Query networks: text. An agent extracts one controlled name. The caller cannot supply a schema.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• text, required. Text to read. The full request, including the fixed prompt and schema, must stay within the tier input ceiling.
• tier, optional. Optional. Standard is the default. Large must be explicit and uses the large price.

Output

data.value contains only name. The caller cannot choose a schema, model, or tool. Standard and Large use the same prices and token ceilings as Text Summarization. Invalid input is HTTP 400 before payment. A name that is blank or longer than 80 characters is not settled.

{
  "text": "The token name is USDC."
}

{
  "ok": true,
  "service": "ai.extract",
  "data": {
    "tier": "standard",
    "value": {
      "name": "USDC"
    }
  }
}

Text Classification, AI

POST /api/v1/text-classification costs 0.002 USDC (2000 atomic units). Classifies text as positive, negative, or neutral. Standard only, 0.002 USDC. Test price, not a formal sale price.

Query networks: text. An agent classifies one text as positive, negative, or neutral. Large is rejected.

Send Content-Type: application/json. Extra JSON fields are rejected before payment.

Input

• text, required. Text to classify. The full request, including the fixed prompt and schema, must stay within the standard input ceiling.
• tier, optional. Optional. Only standard is accepted. Large is rejected.

Output

data.label is positive, negative, or neutral. Only Standard is accepted, with 2000 input tokens, 128 output tokens, and 2000 atomic units. Large is HTTP 400 before payment. An unknown label, refusal, incomplete output, usage over the ceiling, upstream failure, and timeout are not settled.

{
  "text": "The payment settled."
}

{
  "ok": true,
  "service": "ai.classify",
  "data": {
    "tier": "standard",
    "label": "positive"
  }
}

Health check

GET /api/health reports the service and database. verbose is optional and accepts only true or false. true adds a timestamp. This route is free.

{
  "ok": true,
  "status": "ok",
  "service": "x402-api-marketplace",
  "checks": { "app": "ok", "database": "ok" }
}

Agent discovery

GET /api/discovery/resources lists only the priced routes. It is free and uses the x402 v2 discovery document. Each item uses the specification fields resource, type, x402Version, accepts, lastUpdated, description, mimeType, serviceName, and the bazaar extension. The accepts entry matches the 402 challenge for the documented example body: the same scheme, network, asset, amount, and receiving address. Text Summarization and Structured Extraction document the standard price in that example. A request that sets tier to large receives its own 402 for the large price. Text Classification has no large price. CDP Bazaar does not use a separate registration call. It indexes this same extension after a successful facilitator settlement whose payload includes resource and extensions.bazaar. This server does not upload a catalog or call the facilitator validate endpoint. Optional filters are type, payTo, scheme, network, extensions, limit, and offset.

Errors

Wallet Activity is not available. It has no price and no payment route.

A failed request returns one JSON object. Invalid input returns VALIDATION_ERROR. An unknown /api path returns NOT_FOUND. A failed database check returns DATABASE_UNAVAILABLE.

• 400 VALIDATION_ERROR: the JSON body or query is invalid. Extra fields are not allowed.
• 400 PAYLOAD_TOO_LARGE: PAYMENT-SIGNATURE is longer than 8192 characters.
• 402 PAYMENT_REQUIRED: the payment is missing, invalid, mismatched, rejected, or failed verification.
• 403 PAYMENT_NOT_ENABLED: real facilitator settlement is disabled in this server environment. No API result is delivered.
• 404 NOT_FOUND: the API path is not published.
• 409 PAYMENT_REPLAY: that authorization was already used for a different request.
• 409 PAYMENT_STATE: the payment is already being processed, or a query that may have started will not be repeated.
• 503 PAYMENT_STATE: the payment is settled, but the stored result cannot be resent.
• 409 PAYMENT_SETTLEMENT_UNKNOWN: settlement was not confirmed. The result is not returned.
• 413 PAYLOAD_TOO_LARGE: the JSON body is larger than 100 KB.
• 502 UPSTREAM_ERROR: the upstream request failed.
• 503 UPSTREAM_UNAVAILABLE: the upstream did not complete the request.
• 503 NETWORK_ERROR: verification could not be completed, and the payment was not settled.
• 503 PROVIDER_NOT_CONFIGURED: the provider or CDP credential is not configured.
• 503 DATABASE_UNAVAILABLE: the health check cannot use the database.

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [{ "field": "hash", "message": "must be a 0x-prefixed 32-byte hex value" }]
  }
}