Application RPC contract

Read state and submit canonical Quantum transactions.

Quantum nodes expose JSON-RPC 2.0. New applications should use the chain-native qc namespace. Current nodes also provide an eth compatibility alias, but Ethereum signing and serialization are not compatible.

Connect Conventions Methods Transactions and receipts Logs Errors and retries Security

Connect

Prove the network before using it.

Sandbox RPChttps://rpc.sandbox.qustody.io

Chain ID20804 / 0x5144

Genesis0x3d9c68...c8997e7

chain ID

curl --fail-with-body https://rpc.sandbox.qustody.io \
  -H 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"qc_chainId","params":[]}'

genesis block

curl --fail-with-body https://rpc.sandbox.qustody.io \
  -H 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":2,"method":"qc_getBlockByNumber","params":["0x0",false]}'

The first response must contain result: "0x5144". The second must contain the full published Sandbox genesis hash. The SDK performs both checks through validateNetwork().

Hosted accessHTTP 403 means the request did not pass Sandbox source controls or rate policy. It is not a JSON-RPC error. Ask Quantum Chain to approve the application’s public egress address.

Wire conventions

JSON-RPC types are not normal JSON numbers.

Quantity: A minimal 0x-prefixed hexadecimal integer. Zero is 0x0, not 0x00. Examples include block number, nonce, balance, gas, and fee values.
Binary data: An even-length 0x-prefixed hexadecimal byte string. Empty bytes are 0x.
Address: Exactly 20 bytes, displayed as 0x plus 40 hexadecimal characters.
Hash: Exactly 32 bytes, displayed as 0x plus 64 hexadecimal characters.
Block selector: A block-number quantity or a supported tag such as latest, earliest, or pending.
Call object: An object with fields such as from, to, gas, fee fields, value, and binary data.

Currency unitsRPC values are integer atomic units. One Quantum equals 10¹⁸ atomic units. Use parseQuantum and formatQuantum instead of JavaScript floating-point arithmetic.

Method browser

Click a method to see its inputs and output.

Each entry includes a copyable request against Quantum Sandbox. Replace placeholder addresses, hashes, filter IDs, and raw transactions before running it.

Transaction lifecycle

Submission is not confirmation.

qc_sendRawTransaction accepts one complete, already-signed Quantum transaction and returns its transaction hash. A returned hash means the node accepted the bytes for processing. It does not mean the transaction executed successfully.

submit raw transaction

curl --fail-with-body https://rpc.sandbox.qustody.io \
  -H 'content-type: application/json' \
  --data '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"qc_sendRawTransaction",
    "params":["0xREPLACE_WITH_SDK_RAW_TRANSACTION"]
  }'

poll receipt

curl --fail-with-body https://rpc.sandbox.qustody.io \
  -H 'content-type: application/json' \
  --data '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"qc_getTransactionReceipt",
    "params":["0xREPLACE_WITH_TRANSACTION_HASH"]
  }'

The receipt is null before inclusion. After inclusion, require status: "0x1". A receipt with status: "0x0" records a failed execution and must not be treated as success.

Nonce ownership

Use qc_getTransactionCount(address, "pending") when preparing a new transaction.
Serialize automatic submissions per sender so two processes do not allocate the same nonce.
A nonce gap leaves later transactions queued until the missing nonce is accepted.
Replacement uses the same nonce and fee rules accepted by the target node. Reconcile the existing transaction before replacing it.

Contracts and logs

Use calls for reads and logs for indexed history.

qc_call executes a message against a selected block without creating a transaction. qc_getLogs searches persisted event logs. Stateful filters are convenient but ephemeral and may disappear after gateway or node restarts.

historical logs

curl --fail-with-body https://rpc.sandbox.qustody.io \
  -H 'content-type: application/json' \
  --data '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"qc_getLogs",
    "params":[{
      "fromBlock":"0x1",
      "toBlock":"latest",
      "address":"0xREPLACE_WITH_CONTRACT_ADDRESS",
      "topics":[]
    }]
  }'

A filter uses either blockHash, or a fromBlock and toBlock range. It may also include an address and up to four topic positions. Decode data and topics with the contract ABI.

Failure handling

Separate HTTP, JSON, RPC, and transaction failures.

Failure	Meaning	Action
HTTP 403	Edge access or rate policy rejected the request	Stop retries and verify source authorization
HTTP 429	Rate limit	Back off with a bounded delay
HTTP 5xx or timeout	Outcome may be unknown	Retry reads. Reconcile writes by local hash before deciding
Malformed JSON or ID mismatch	Untrusted or broken upstream response	Reject the response
JSON-RPC `error`	The node rejected the method or request	Use its code, message, and safe data to classify the failure
Receipt status `0x0`	On-chain execution failed	Record failure and inspect execution context

Write retry ruleNever blindly retry qc_sendRawTransaction. The first request may have reached the node even when its response was lost. Retain the SDK’s locally computed transaction hash, query it, and reconcile the pending nonce.

Public and operator APIs

Expose the smallest application surface.

Normal applications need selected qc, net, and web3 methods. Administrative, debug, personal, miner, engine, and transaction-pool APIs are node-operator surfaces. Do not expose them through a public gateway.

Use HTTPS for remote RPC and set a request deadline.
Limit request and response sizes.
Validate every response envelope and method-specific result.
Keep node account unlocking and signing disabled on public RPC.
Apply source controls, rate limits, and method allowlists at the edge.
Use the SDK’s full client or typed wrappers when they cover the method.

Typed JavaScript clientNetwork validation, normalized values, submission, and receipts.Node operationsPrivate listeners, runtime profiles, metrics, and troubleshooting.