HTTP endpoint reference

Base URLs and conventions

Network	Base URL
Base	`https://api.ctoken.inco.org/api`
Base Sepolia	`https://api.ctoken.testnet.inco.org/api`

Routes are relative to these URLs. GET requires no signature; POST consent does. Amounts/blocks are decimal strings. Token paths take cToken addresses except /icon, which takes the underlying asset. Pagination: page=1, limit=10, maximum 100. Send positive integers.

API=https://api.ctoken.testnet.inco.org/api
OWNER=0x0000000000000000000000000000000000000001
USDC=0x036CbD53842c5426634e7929541eC2318f3dCF7e

curl -sS "$API/factory"
curl -sS "$API/wallets/$OWNER/assets"
curl -sS "$API/wallets/$OWNER/transactions?page=1&limit=10"
curl -sS "$API/prices?tokens=$USDC"

GET /tokens

Lists all indexed wrappers, newest created first. No pagination parameters. Returns TokenRow[]:

type TokenRow = {
  address: string;       // cToken
  base_erc20: string;
  name: string;
  symbol: string;
  decimals: number;
  created_blk: string | null;
};

Missing metadata defaults to empty name/symbol and 18 decimals. Read on-chain decimals for transaction precision. No SDK tokens() method.

GET /tokens/:address

Returns TokenRow or HTTP 200 JSON null if unindexed. A missing record does not prove non-deployment.

GET /tokens/:address/flows

Public flow feed for a cToken. Query page, limit. Returns the common page envelope with items containing kind, account, amount, success_handle, block_number, block_time, and tx_hash. Amounts are base-unit decimal strings; nullable fields can occur. Ordered by block/log descending.

GET /tokens/:address/activity

Confidential event feed for a cToken. Query page, limit. Page item fields: kind, from_addr, to_addr, handle, block_number, block_time, tx_hash. This feed exposes handles, not decrypted amounts. Addresses/handles may be null depending on the event.

GET /tokens/:address/disclosures

Disclosure feed for a cToken. Query page, limit. Page item fields: handle, amount, block_number, block_time, tx_hash. Amounts are publicly disclosed base-unit values; this endpoint does not authorize new disclosure. Ordered by block descending.

{
  "items": [],
  "total": 0,
  "page": 1,
  "pages": 1,
  "limit": 10
}

Token feeds and wallet transactions share this envelope. Hosted responses keep pages at least 1, including empty results.

GET /wallets/:address/assets

Lists indexed holdings for a wallet, descending last activity block. Returns the Asset[] schema. Empty wallet: []. There is no pagination. SDK equivalent: ctoken.assets({ address }).

GET /wallets/:address/transactions

Combined cross-token wallet activity. Query page, limit. Returns TxPage. Confidential transfers and public flows share the normalized transaction schema; internal mint/burn legs are excluded. SDK equivalent: ctoken.history({ address, page, limit }).

GET /wallets/:address/operators

Unpaginated array: token, operator, until (Unix seconds string), active (expiry > server time), block_number, tx_hash. Newest block first; expired approvals remain with active: false. No SDK wrapper.

GET /factory

Indexed deployment state:

Field	Meaning
`chainId`, `network`	Source deployment identity; server `network` label is not necessarily the SDK’s NetworkName value.
`factory`, `vault`	Indexed deployment addresses.
`paused`	Latest indexed pause state, false before a state row is present.
`blocklist`, `blocklistEnabled`	Indexed restriction configuration; null/false defaults.
`implementation`	Current indexed implementation address or null.
`updatedBlock`	Last indexed state-update block string or null.

These snapshots can lag chain state. The SDK does not fetch them before operations.

GET /tokens/:address/icon

Underlying token/price-reference icon: HTTP 302 to a CDN image, cached 86400 seconds. Invalid address: 400; unknown icon: 404. Supply an image fallback.

GET /prices

Query tokens: comma-separated underlying addresses, at most 200; omit for available cached prices. Returns Prices. Hosted TTL defaults to 600 seconds; read the response’s ttl. Returns { consented: boolean, version: string, signedAt: number | null } for current terms; timestamp is Unix seconds. Consent is separate from allowances and reveal sessions. JSON body: { address: string, signedAt: number, signature: string }. Unix timestamp must be nonnegative and at most 300 seconds ahead. A valid signature records acceptance; success is HTTP 200 { "ok": true }.

Status	Body	Meaning
400	`{ "error": "bad json" }`	Body cannot be parsed.
400	`{ "error": "bad body" }`	Required primitive fields missing/wrong type.
400	`{ "error": "bad timestamp" }`	Timestamp outside the accepted range.
401	`{ "error": "bad signature" }`	Signature cannot establish acceptance.
503	`{ "error": "verification unavailable" }`	Verification service/RPC temporarily unavailable.

Canonical message (newline-separated, lowercase address):

CToken - Terms Acceptance

I have read and agree to the Inco Terms of Service (https://www.inco.org/terms-of-services) and Privacy Notice (https://www.inco.org/privacy).
Version: 2
Terms Hash: f2b10bc5e255454136696a9d007725af4920596ce78e2cc551d6e91d94bca018
Address: <lowercase wallet address>
Signed At: <Unix seconds>

Replace placeholders and sign with walletClient.signMessage({ account: walletClient.account, message }); POST the address, timestamp, and signature. Confirm the service’s current terms version/hash before signing. No SDK consent helper.

Operational routes and CORS

Route / method	Behavior
`GET /obs/metrics`	Indexer-owned Prometheus exposition combining Ponder metrics and application observations. Returns 500 text if local Ponder metrics cannot be read.
GET `/health`	Framework-owned Ponder endpoint; exposure and exact response follow the deployed framework/ingress.
GET `/ready`	Framework-owned readiness endpoint.
GET `/metrics`	Framework-owned metrics endpoint.
GET `/status`	Framework-owned indexing/status endpoint.
OPTIONS on application routes	CORS middleware handles browser preflight. Allowed origins depend on the service configuration; production access is described below.

Hosted ingress does not expose these five operational paths. Use internal monitoring URLs; their public 404s do not indicate API failure. Other failures: 500 (internal error), 429 (rate limited), or 503 (busy). Honor Retry-After on rate limits/load shedding. GET responses may be cached or stale; capacity limits vary by deployment.

Production origins

Request hosted access through the origin whitelist form. For your backend, see compatibility and CORS.

Get started

Integrations

SDK reference

Indexer & raw APIs

Operations

HTTP endpoint reference

Base URLs and conventions

GET /tokens

GET /tokens/:address

GET /tokens/:address/flows

GET /tokens/:address/activity

GET /tokens/:address/disclosures

GET /wallets/:address/assets

GET /wallets/:address/transactions

GET /wallets/:address/operators

GET /factory

GET /tokens/:address/icon

GET /prices

Operational routes and CORS

Production origins

​Base URLs and conventions

​GET /tokens

​GET /tokens/:address

​GET /tokens/:address/flows

​GET /tokens/:address/activity

​GET /tokens/:address/disclosures

​GET /wallets/:address/assets

​GET /wallets/:address/transactions

​GET /wallets/:address/operators

​GET /factory

​GET /tokens/:address/icon

​GET /prices

​GET /consent/:address

​POST /consent

​Operational routes and CORS

​Production origins

Base URLs and conventions

GET /tokens

GET /tokens/:address

GET /tokens/:address/flows

GET /tokens/:address/activity

GET /tokens/:address/disclosures

GET /wallets/:address/assets

GET /wallets/:address/transactions

GET /wallets/:address/operators

GET /factory

GET /tokens/:address/icon

GET /prices

GET /consent/:address

POST /consent

Operational routes and CORS

Production origins