- API Reference
JSON-RPC API
Direct Fast proxy JSON-RPC endpoints and network configuration, distinct from the REST transport used by the core SDK.
The Fast proxy has a low-level JSON-RPC 2.0 interface. The current @fastxyz/sdk uses the separate REST proxy interface (/proxy-rest), not this JSON-RPC endpoint. For new SDK integrations, use the Fast SDK reference and REST API. Keep direct JSON-RPC callers pinned to the server API they have validated; this page does not establish that every older method or response shape is supported by every deployment.
This page is for developers who need direct access to the protocol-level endpoints.
Endpoints
Section titled “Endpoints”| Network | Proxy RPC |
|---|---|
| Mainnet | https://api.fast.xyz/proxy |
| Testnet | https://testnet.api.fast.xyz/proxy |
| Network | SDK default token | Token ID |
|---|---|---|
| Mainnet | fastUSD | c655a12330da6af361d281b197996d2bc135aaed3b66278e729c2222291e9130 |
| Testnet | testUSDC | d73a0679a2be46981e2a8aedecd951c8b6690e7d5f8502b34ed3ff4cc2163b46 |
All requests are POST with Content-Type: application/json.
Request
Section titled “Request”{ "jsonrpc": "2.0", "id": 1, "method": "<method_name>", "params": { ... }}Responses
Section titled “Responses”For a JSON-RPC response, inspect the result or error member. Do not assume every transport failure returns HTTP 200 or that an absent response means a transaction was not submitted.
Success Response
{ "jsonrpc": "2.0", "id": 1, "result": { ... }}Error Response
{ "jsonrpc": "2.0", "id": 1, "error": { "code": "<error_code>", "message": "<error_message>", "data": "<additional_data>" }}Methods
Section titled “Methods”| Method | Purpose |
|---|---|
proxy_submitTransaction |
Submit a signed transaction — returns a certificate on success |
proxy_getAccountInfo |
Query account balance, nonce, token holdings, and certificates |
proxy_getTokenInfo |
Look up token metadata (name, decimals, supply, admin, minters) |
proxy_submitTransaction
Section titled “proxy_submitTransaction”Submit a signed transaction to the network. The proxy handles the full settlement lifecycle: it broadcasts the transaction to all validators, collects their signatures, assembles a certificate once quorum is reached, and submits the certificate back to validators for settlement.
Parameters:
| Field | Type | Description |
|---|---|---|
transaction |
Transaction |
The transaction to submit |
signature |
SignatureOrMultiSig |
Ed25519 signature over the BCS-serialized transaction |
Returns: ProxySubmitTransactionResult
{ "Success": TransactionCertificate }— transaction settled, certificate returned{ "IncompleteMultiSig": [...] }— multisig transaction stored, awaiting additional signatures
Example request
curl -X POST 'https://testnet.api.fast.xyz/proxy' \ --header 'Content-Type: application/json' \ --data '{ "jsonrpc": "2.0", "id": 1, "method": "proxy_submitTransaction", "params": { "transaction": { "network_id": "fast:testnet", "sender": [54,128,54,206,88,243,124,101,147,238,105,180,78,172,190,12,193,195,118,236,177,124,79,251,192,63,114,196,255,73,74,81], "nonce": 0, "timestamp_nanos": 1769705752161000000, "claim": { "TokenTransfer": { "recipient": [75,164,223,195,221,101,117,31,251,60,194,50,41,1,83,17,79,28,61,165,140,36,12,127,122,60,161,218,118,145,112,210], "token_id": [250,87,94,112,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0], "amount": "ffff", "user_data": null } }, "archival": false }, "signature": { "Signature": [228,162,180,83,46,167,133,230,176,100,60,110,57,65,23,113,101,204,242,193,125,59,88,232,122,6,90,118,41,159,94,108,20,181,224,234,57,42,35,95,4,186,62,128,68,213,212,46,214,155,241,163,147,120,155,69,201,1,29,63,106,22,75,15] } } }'Example response
{ "jsonrpc": "2.0", "id": 1, "result": { "Success": { "envelope": { "transaction": { "network_id": "fast:testnet", "sender": [54,128,54,206,...], "nonce": 0, "timestamp_nanos": 1769705752161000000, "claim": { "TokenTransfer": { "recipient": [75,164,223,195,...], "token_id": [250,87,94,112,0,...], "amount": "ffff", "user_data": null } }, "archival": false }, "signature": { "Signature": [228,162,180,83,...] } }, "signatures": [ [[223,165,168,37,...], [95,227,196,114,...]], [[236,249,103,252,...], [80,65,124,70,...]], [[150,20,92,12,...], [26,229,199,218,...]] ] } }}proxy_getAccountInfo
Section titled “proxy_getAccountInfo”Query account information from a validator known to the proxy.
Parameters:
| Field | Type | Description |
|---|---|---|
address |
Array<uint8; 32> |
The account’s Ed25519 public key |
token_balances_filter |
Array<TokenId> or null |
Which token balances to return. null = none; [] = all tokens held |
state_key_filter |
Array<StateKey> or null |
Which state fields to return. null = none; [] = all |
certificate_by_nonce |
NonceRange or null |
Currently not unabled |
Returns: AccountInfoResponse
Example request
curl -X POST 'https://testnet.api.fast.xyz/proxy' \ --header 'Content-Type: application/json' \ --data '{ "jsonrpc": "2.0", "id": 1, "method": "proxy_getAccountInfo", "params": { "address": [54,128,54,206,88,243,124,101,147,238,105,180,78,172,190,12,193,195,118,236,177,124,79,251,192,63,114,196,255,73,74,81], "token_balances_filter": [], "state_key_filter": null, "certificate_by_nonce": null } }'Example response
{ "jsonrpc": "2.0", "id": 1, "result": { "sender": [54,128,54,206,...], "balance": "de0b6b3a7640000", "next_nonce": 3, "pending_confirmation": null, "requested_state": [], "requested_certificates": null, "requested_validated_transaction": null, "token_balance": [ [[250,87,94,112,0,...], "de0b6b3a7640000"] ] }}proxy_getTokenInfo
Section titled “proxy_getTokenInfo”Look up metadata for one or more tokens.
Parameters:
| Field | Type | Description |
|---|---|---|
token_ids |
Array<Array<uint8; 32>> |
Token IDs to look up |
Returns: TokenInfoResponse
Example request
curl -X POST 'https://testnet.api.fast.xyz/proxy' \ --header 'Content-Type: application/json' \ --data '{ "jsonrpc": "2.0", "id": 1, "method": "proxy_getTokenInfo", "params": { "token_ids": [ [250,87,94,112,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0] ] } }'Example response
{ "jsonrpc": "2.0", "id": 1, "result": { "requested_token_metadata": [ [ [250,87,94,112,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0], { "update_id": 0, "admin": [0,0,...], "token_name": "SET", "decimals": 18, "total_supply": "52b7d2dcc80cd2e4000000", "mints": [] } ] ] }}Transaction Signing
Section titled “Transaction Signing”To submit a transaction, you must sign it locally before sending it to the proxy.
1. Serialize
Section titled “1. Serialize”Serialize the Transaction struct using BCS (Binary Canonical Serialization).
BCS libraries:
- TypeScript/JavaScript:
@mysten/bcs - Rust:
bcs(as aserdebackend)
Special rule: Numerical string fields (Amount / Balance) are encoded as little-endian unsigned 256-bit integers (32 bytes) during BCS serialization.
2. Prefix
Section titled “2. Prefix”Prepend the UTF-8 string "Transaction::" to the serialized bytes.
3. Sign
Section titled “3. Sign”Sign the prefixed bytes with Ed25519 using the sender’s private key:
signature = ed25519_sign(private_key, "Transaction::" + BCS(transaction))4. Hash
Section titled “4. Hash”The transaction hash is the keccak256 digest of the BCS-serialized transaction (without the prefix):
tx_hash = keccak256(BCS(transaction))5. Submit
Section titled “5. Submit”Wrap the signature in a SignatureOrMultiSig envelope and call proxy_submitTransaction.
Data Encoding
Section titled “Data Encoding”| Concept | Format | Example |
|---|---|---|
| Addresses | 32-byte Ed25519 public key, as JSON array of unsigned integers | [54,128,54,206,...,74,81] |
| User-facing addresses | bech32m with fast prefix (SDK only, not used in RPC) |
fast1qxy2kgdy... |
| Amounts | Hex-encoded unsigned 256-bit integer (no 0x prefix) |
"de0b6b3a7640000" |
| Timestamps | uint128 nanoseconds since Unix epoch |
1769705752161000000 |
| Nonces | uint64, auto-incrementing per account, starting at 0 |
0, 1, 2, … |
Data Types
Section titled “Data Types”Transaction
Section titled “Transaction”The core unit submitted to the network.
| Field | Type | Description |
|---|---|---|
network_id |
string |
The id of the network (e.g., “fast:mainnet”, “fast:testnet”). Follows CAIP-2 standard |
sender |
Array<uint8; 32> |
Sender’s Ed25519 public key |
nonce |
uint64 |
Sequence number — must match the account’s next_nonce |
timestamp_nanos |
uint128 |
Nanoseconds since Unix epoch |
claim |
ClaimType |
The operation to perform |
archival |
boolean |
Currently disabled |
fee_token |
TokenId or null |
The fee token to use to pay for this transaction. See more details below. |
Fee token
Section titled “Fee token”A transaction may include
fee_token. Do not assume that an omitted value means USDC on every network: the current SDK network defaults arefastUSDon mainnet andtestUSDCon testnet. Confirm accepted fee tokens with the target deployment before submitting a transaction directly through JSON-RPC.
ClaimType
Section titled “ClaimType”Determines the operation packed into a transaction.
| Variant | Type | Description |
|---|---|---|
TokenTransfer |
TokenTransfer |
Transfer tokens to the recipient |
TokenCreation |
TokenCreation |
Create a new custom token |
TokenManagement |
TokenManagement |
Modify a custom token (admin, minters) |
Mint |
Mint |
Mint additional supply of a custom token |
Burn |
Burn |
Burn an amount of a custom token |
ExternalClaim |
ExternalClaim |
Submit arbitrary data with verifier signatures |
Batch |
OperationBundle |
Bundle multiple operations in one transaction |
TokenTransfer
Section titled “TokenTransfer”| Field | Type | Description |
|---|---|---|
recipient |
Array<uint8; 32> |
Recipient address |
token_id |
Array<uint8; 32> |
Token ID to transfer |
amount |
Amount |
Amount in raw units (hex string) |
user_data |
Array<uint8; 32> or null |
Optional arbitrary data |
TokenCreation
Section titled “TokenCreation”| Field | Type | Description |
|---|---|---|
token_name |
string |
Human-readable name |
decimals |
uint8 |
Decimal places (0–18) |
initial_amount |
Amount |
Initial supply, credited to the creator |
mints |
Array<Array<uint8; 32>> |
Addresses authorized to mint more supply |
user_data |
Array<uint8; 32> or null |
Optional arbitrary data |
The token ID is derived from the keccak256 hash of the BCS-serialized transaction that creates the token.
TokenManagement
Section titled “TokenManagement”| Field | Type | Description |
|---|---|---|
token_id |
Array<uint8; 32> |
Token to manage |
update_id |
uint64 |
Sequencing counter — must increment by 1 each update |
new_admin |
Array<uint8; 32> or null |
New admin address, or null to keep current |
mints |
Array<[AddressChange, Array<uint8; 32>]> |
Minter addresses to add or remove |
user_data |
Array<uint8; 32> or null |
Optional arbitrary data |
AddressChange is either { "Add": [...] } or { "Remove": [...] }.
Sender must be an authorized minter for the token.
| Field | Type | Description |
|---|---|---|
recipient |
Array<uint8; 32> |
Recipient address |
token_id |
Array<uint8; 32> |
Token to mint |
amount |
Amount |
Amount to mint |
| Field | Type | Description |
|---|---|---|
token_id |
Array<uint8; 32> |
Token to burn |
amount |
Amount |
Amount to burn |
ExternalClaim
Section titled “ExternalClaim”Submit arbitrary data verified by a set of external verifiers.
| Field | Type | Description |
|---|---|---|
verifier_committee |
Array<Array<uint8; 32>> |
Verifier public keys |
verifier_quorum |
uint64 |
Minimum verifier signatures required |
claim_data |
Array<uint8> |
Arbitrary data payload |
signatures |
Array<VerifierSig> |
Verifier signatures over the transaction |
Each VerifierSig contains verifier_addr (public key) and sig (Ed25519 signature over the Transaction struct without verifier signatures).
OperationBundle
Section titled “OperationBundle”An array of Operation objects. Each Operation is one of: TokenTransfer (with explicit recipient), TokenCreation, TokenManagement, ExternalClaim, Mint (with explicit recipient), or Burn.
The TokenTransfer and Mint variants inside a bundle include a recipient field, since the bundle allows operations targeting different recipients within a single transaction.
Response Types
Section titled “Response Types”AccountInfoResponse
| Field | Type | Description |
|---|---|---|
sender |
Array<uint8; 32> |
Account address |
balance |
Balance |
Native SET balance (hex string) |
next_nonce |
uint64 |
Next valid nonce for this account |
pending_confirmation |
ValidatedTransaction or null |
Transaction validated but not yet confirmed |
requested_state |
Array<[StateKey, State]> |
Requested state fields |
requested_certificates |
Array<TransactionCertificate> or null |
Certificates in the requested nonce range |
token_balance |
Array<[TokenId, Balance]> |
Custom token balances |
TokenInfoResponse
| Field | Type | Description |
|---|---|---|
requested_token_metadata |
Array<[TokenId, TokenMetadata]> |
Token ID → metadata pairs |
TokenMetadata fields: update_id, admin, token_name, decimals, total_supply, mints.
TransactionCertificate
| Field | Type | Description |
|---|---|---|
envelope |
TransactionEnvelope |
The transaction + sender’s signature |
signatures |
Array<[PublicKeyBytes, Signature]> |
Validator signatures forming the quorum |
TransactionEnvelope contains transaction (Transaction) and signature (SignatureOrMultiSig).
ProxySubmitTransactionResult
| Variant | Payload | Description |
|---|---|---|
Success |
TransactionCertificate |
Transaction settled successfully |
IncompleteMultiSig |
array |
Multisig transaction stored, awaiting more signatures |
Primitive Types
Section titled “Primitive Types”| Type | Format | Description |
|---|---|---|
Amount |
Hex string (unsigned 256-bit) | Token amount in raw units. Example: "de0b6b3a7640000" = 10¹⁸ = 1 SET |
Balance |
Hex string (signed 257-bit) | Like Amount, but may be negative (prefixed with -) |
Nonce |
uint64 |
Sequence number |
NonceRange |
{ start: Nonce, limit: uint } |
Range query for certificates |
PublicKeyBytes |
Array<uint8; 32> |
Ed25519 public key |
Signature |
Array<uint8; 64> |
Ed25519 signature |
SignatureOrMultiSig |
{ "Signature": [...] } or { "MultiSig": { config, signatures } } |
Single or multisig authentication |
TokenId |
Array<uint8; 32> |
Unique token identifier |
StateKey |
Array<uint8; 32> |
Account state field key |
State |
Array<uint8; 32> |
Account state field value |
UserData |
Array<uint8; 32> or null |
Optional arbitrary data attached to a transaction |
MultiSig
Section titled “MultiSig”For accounts controlled by multiple signers.
MultiSigConfig — determines the multisig account address:
| Field | Type | Description |
|---|---|---|
authorized_signers |
Array<PublicKeyBytes> |
Accounts that may sign |
quorum |
uint64 |
Minimum signatures required |
nonce |
uint64 |
Distinguishes multiple multisig accounts with the same committee |
MultiSig — authentication envelope:
| Field | Type | Description |
|---|---|---|
config |
MultiSigConfig |
The account’s multisig configuration |
signatures |
Array<[PublicKeyBytes, Signature]> |
Signatures from authorized signers |
Error Codes
Section titled “Error Codes”Standard JSON-RPC 2.0 error codes plus application-specific codes:
| Code | Message | Description |
|---|---|---|
-32700 |
Parse error | Malformed JSON in request body |
-32601 |
Method not found | The requested method does not exist |
-32602 |
Invalid params | Missing or invalid parameters |
-32014 |
Unexpected Nonce | The nonce of the transaction is incorrect |
-32015 |
Invalid Request | The transaction exceeds various limits (size, number of signatures, token name length, number of minters, number of claims in batch) |
-32000 |
General Error | Other general errors |
Architecture Note
Section titled “Architecture Note”The proxy is a convenience layer — it is not part of the trust model. It relays messages, aggregates signatures, and assembles certificates, but it cannot forge signatures or alter transactions. Anyone can run a proxy.
In the current network configuration, validators are not directly accessible. All traffic routes through the proxy service. This is a temporary operational decision to prevent DDoS attacks — not a protocol requirement. The protocol itself is fully functional with direct client-to-validator communication.