Skip to content
Fast
API Reference

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.


NetworkProxy RPC
Mainnethttps://api.fast.xyz/proxy
Testnethttps://testnet.api.fast.xyz/proxy
NetworkSDK default tokenToken ID
MainnetfastUSDc655a12330da6af361d281b197996d2bc135aaed3b66278e729c2222291e9130
TestnettestUSDCd73a0679a2be46981e2a8aedecd951c8b6690e7d5f8502b34ed3ff4cc2163b46

All requests are POST with Content-Type: application/json.

{
"jsonrpc": "2.0",
"id": 1,
"method": "<method_name>",
"params": { ... }
}

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>"
}
}

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)

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
Terminal window
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,...]]
]
}
}
}

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
Terminal window
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"]
]
}
}

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
Terminal window
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": []
}
]
]
}
}

To submit a transaction, you must sign it locally before sending it to the proxy.

Serialize the Transaction struct using BCS (Binary Canonical Serialization).

BCS libraries:

Special rule: Numerical string fields (Amount / Balance) are encoded as little-endian unsigned 256-bit integers (32 bytes) during BCS serialization.

Prepend the UTF-8 string "Transaction::" to the serialized bytes.

Sign the prefixed bytes with Ed25519 using the sender’s private key:

signature = ed25519_sign(private_key, "Transaction::" + BCS(transaction))

The transaction hash is the keccak256 digest of the BCS-serialized transaction (without the prefix):

tx_hash = keccak256(BCS(transaction))

Wrap the signature in a SignatureOrMultiSig envelope and call proxy_submitTransaction.


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, …

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.

A transaction may include fee_token. Do not assume that an omitted value means USDC on every network: the current SDK network defaults are fastUSD on mainnet and testUSDC on testnet. Confirm accepted fee tokens with the target deployment before submitting a transaction directly through JSON-RPC.

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
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
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.

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

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).

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.


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

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

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

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

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.