Skip to main content
Cowboy’s network answers HTTP at its RPC endpoint. The cowboy CLI and the client SDK are wrappers over this API, so you can do what they do with plain HTTP. The examples on this page use an $RPC variable. On Cloud:
For a network on your own machine, use http://localhost:4000.

Conventions

  • Addresses are 20-byte hex strings (0x-prefixed accepted). Invalid addresses return 400.
  • Pagination: list endpoints take offset and limit query params (limit defaults to 50, capped at 1,000) and return total_count with the echoed offset/limit; the actor storage/mailbox endpoints use cursor pagination (next_cursor).
  • Rate limits: exceeding the limit returns 429. Back off and retry.
  • Errors are JSON with an HTTP status plus a numeric code (table below).
  • Body size: requests are capped at 1 MB globally; /submit and /submit_wait enforce a tighter 512 KB.
  • Amounts (balances, fees) are integers in CBY base units (1 CBY = 10⁹).

Transactions

The submission body is binary CBOR, not JSON: a Submission::Transactions([...]) envelope of signed transactions (max 50 per batch). In practice you produce it with the CLI (cowboy transaction submit) or an SDK rather than by hand; the wallet’s transaction encoding is byte-compatible with the node’s deterministic CBOR. /submit_wait returns per-transaction results including status, block_height, gas used, and revert_reason when execution failed.

Accounts

Actors

The /actor/{address} storage map is a bounded preview of committed state. storage_truncated is true when more than 1,000 enumerable rows exist. A false flag does not mean all stored keys are present: storage listings enumerate only verbatim keys of at most 32 bytes. Longer keys remain accessible through /actors/{address}/storage/value, but cannot be enumerated. Use /actors/{address}/storage to page through the enumerable rows. Paginated listings merge pending writes; the pages are not one committed snapshot of the preview. /actor/read runs a handler against current state without a transaction — the workhorse for UIs and polling:
The payload can be given as payload (base64 bytes), payload_text (UTF-8 string), or payload_json (JSON value); optional max_cycles/max_cells bound the execution. A handler that attempts a state write is rejected (error 5003).

Blocks and chain state

Tokens (CIP-20)

Runners and jobs (CIP-2)

Read endpoints useful when integrating with off-chain compute: The runner daemon itself uses signed POST flows (/runner/{address}/heartbeat, /runner/{address}/job_result, …): each has a companion *_payload GET that returns the exact message_to_sign_base64, so signatures are computed over server-canonical bytes.

Proofs (CIP-15/17)

/proof/receipt/{tx_hash}, /proof/tx/{tx_hash}, /proof/account/{address}, /proof/actor/{address}, /proof/storage/{address}/{key}, and batch /proof/multi (POST) return Merkle proofs against the block state root, for light-client-style verification. /state/{actor}/{key_hex} returns a storage value together with its proof.

Other endpoint families

Error codes

Numeric codes accompany HTTP errors so clients can branch reliably: Execution-level failures inside a committed transaction surface as E-codes in the receipt instead — see the error reference.

Next