Skip to content
Fast
Fast (Archived) / Developers / Fast APIArchived

Proxy API

View as Markdown

Submitting to Proxy

proxy_submitTransactionSubmits a signed transaction to the proxy.
proxy_faucetDripDistribute funds from the proxy's account to the specified account.
proxy_evmSignCertificateCross-sign a transaction certificate using secp256k1 for EVM verification.

proxy_submitTransaction

Section titled “proxy_submitTransaction”

Submit a transaction to the proxy to be forwarded to and settled on the network. Upon receipt of the transaction, if the transaction is complete, the proxy will perform the following steps:

  • Submit the signed transaction to all validators known to the proxy.
  • Accumulate signatures from all validators which attest that the transaction is valid.
  • Submit a transaction certificate (composed of the transaction and a quorum of validator signatures) to all validators known to the proxy.

If the transaction is incomplete, the proxy will store the transaction and await additional requests which provide the missing information.

The sender’s transaction signature is computed using Ed25519 where:

  • the public key is stored in Transaction.sender .
  • the message to be signed is the Transaction struct serialized using the BCS format with the following special rule:
    • Numerical string Amount/Balance fields are encoded as a litte-endian unsigned 256-bit number as an array of uint8 of length 32.

BCS serialization libraries are available for several languages:

Parameters
transactionTransaction: A transaction of any ClaimType.
signatureSignatureOrMultiSig: A (multi)signature over the transaction created by Transaction.sender and having the verifier signatures field set to the empty list prior to signing in the case of ExternalClaims.
Returns
ProxySubmitTransactionResultSuccess: with a transaction certificate if the transaction is complete and was successfully submitted and validated. IncompleteMultiSigs: A flag indicating that the transaction is incomplete and has been stored on the proxy for eventual completion and submission.
POST / proxy_submitTransaction

Curl:

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": {
           "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],
           "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],
           "nonce": 0,
           "timestamp_nanos": 1769705752161000000,
           "claim": {
             "TokenTransfer": {
               "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": true
         },
         "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]
         }
       }
     }'

Server response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result":
    {
      "Success":
        {
          "envelope":
            {
              "transaction":
                {
                  "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],
                  "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],
                  "nonce": 0,
                  "timestamp_nanos": 1769705752161000000,
                  "claim":
                    {
                      "TokenTransfer":
                        {
                          "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": true
              },
            "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]
              }
          },
          "signatures":
            [
              [
                [223,165,168,37,72,213,141,191,209,124,158,179,40,24,196,122,92,162,184,248,231,218,132,148,44,167,202,12,126,87,249,141],
                [95,227,196,114,53,242,118,17,88,202,2,186,132,39,158,203,199,42,252,162,208,162,93,83,168,79,145,250,225,228,244,45,131,200,28,80,73,80,213,164,50,7,240,158,32,196,163,193,225,15,169,236,149,62,228,13,149,125,53,158,20,74,115,1]
              ],
              [
                [236,249,103,252,146,0,130,223,133,72,40,87,67,21,187,13,100,52,193,194,242,152,67,181,8,2,150,72,51,230,245,169],
                [80,65,124,70,9,222,103,175,74,243,129,191,79,205,119,80,41,194,224,73,214,119,154,64,107,201,247,238,110,98,151,185,156,47,5,75,247,176,90,179,158,127,26,149,215,45,142,235,120,11,235,165,86,205,247,219,34,166,149,186,163,111,94,9]
              ],
              [
                [150,20,92,12,163,133,206,208,191,189,42,178,133,120,224,172,183,116,145,47,243,232,221,22,110,243,38,177,23,139,10,120],
                [26,229,199,218,49,147,173,149,87,246,144,213,22,73,18,80,3,122,177,18,83,197,212,112,188,76,155,161,2,206,135,224,43,13,117,143,53,255,153,249,50,12,85,129,13,14,128,73,159,238,21,14,19,61,122,202,203,5,247,35,134,61,38,9]
              ]
            ]
        }
    }
}

proxy_faucetDrip

Section titled “proxy_faucetDrip”

Distribute funds from the proxy’s account to the specified account.

Parameters
recipientFastSetAddress: Account that should receive the funds.
amountAmount: Amount of funds that should be added.
token_idOption<TokenId>: If None, funds will be in the default token. If a TokenId is passed, funds will be in that token.
POST / proxy_faucetDrip

Curl:

Terminal window
curl -X POST 'https://testnet.api.fast.xyz/proxy' \
     --header 'Content-Type: application/json' \
     --data '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "proxy_faucetDrip",
       "params": {
         "recipient": [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],
         "amount": "3635c9adc5dea00000",
         "token_id": null
       }
     }'

Note: 3635c9adc5dea00000 = 1000 × 10¹⁸ = 1000 SET in raw units.

Server response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

proxy_evmSignCertificate

Section titled “proxy_evmSignCertificate”

Cross-sign a transaction certificate using secp256k1 for EVM verification. Produces a signature that can be verified by EVM smart contracts, used for bridging and cross-chain verification.

Parameters
certificateTransactionCertificate: The certificate to cross-sign.
Returns
EVM signatureAn EVM-compatible signature object that can be verified by EVM smart contracts, used for bridging and cross-chain verification.
POST / proxy_evmSignCertificate

Curl:

Terminal window
curl -X POST 'https://testnet.api.fast.xyz/proxy' \
     --header 'Content-Type: application/json' \
     --data '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "proxy_evmSignCertificate",
       "params": {
         "certificate": {
           "envelope": {
             "transaction": { "..." : "..." },
             "signature": { "Signature": ["..."] }
           },
           "signatures": [["...", "..."]]
         }
       }
     }'

Querying the Validator

Section titled “Querying the Validator”
proxy_getAccountInfoReturns information regarding a specific account from a validator known to the proxy.
proxy_getTokenInfoReturns information regarding a set of tokens from some validator known to the proxy.

proxy_getAccountInfo

Section titled “proxy_getAccountInfo”

Return information regarding a specific account from some validator known to the proxy.

Parameters
addressFastSetAddress: The designated account to query.
token_balances_filterOption<Vec<TokenId>>: The set of token types for which a balance request will be made. If this parameter is omitted, no custom token balances will be returned. If it is present and empty, the balance of all tokens owned by this account will be queried.
state_key_filterOption<Vec<StateKey>>: The set of state fields created by this account to be returned. If this parameter is omitted, no state fields will be returned; if it is present and empty, all state fields created by this account will be returned.
certificate_by_nonceOption<NonceRange>: If passed, a list of transaction certificates within the nonce range specified by this parameter submitted by account address will be returned (omitting those which do not exist or have been pruned from the validator database).
Returns
AccountInfoResponseAccountInfoResponse for the requested account.
POST / proxy_getAccountInfo

Curl:

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": null,
         "state_key_filter": null,
         "certificate_by_nonce": null
       }
     }'

Server response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result":
    {
      "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],
      "balance": "0",
      "next_nonce": 0,
      "pending_confirmation": null,
      "requested_state": [],
      "requested_certificates": null,
      "requested_validated_transaction": null,
      "token_balance": []
    }
}

proxy_getTokenInfo

Section titled “proxy_getTokenInfo”

Return information regarding a set of tokens from some validator known to the proxy.

Parameters
token_idsVec<TokenId>: An array of TokenIds to look up.
Returns
TokenInfoResponseContains data for all requested tokens.
POST / proxy_getTokenInfo

Curl:

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]
         ]
       }
     }'

Server 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],
            null
          ]
        ]
    }
}

Error Codes

Section titled “Error Codes”

The proxy uses standard JSON-RPC 2.0 error codes, plus custom codes for application-specific errors.

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
-32000 Server error Transaction validation failure (e.g., nonce mismatch, insufficient balance)
-32003 Throttled Rate limit exceeded (e.g., faucet cooldown)

Error response format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "expected nonce is 1 but tx has 0"
  }
}

Some errors include an additional data field with details:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "missing field `certificate` at line 1 column 2"
  }
}