API Reference

This document provides information on the implemented API, along with usage examples.

Pre-requisites

API key This key is essential for most API calls. It can be set in .env file, under the API_KEY variable. In case of a change on the key, there is no need to rebuild docker images, as docker compose will pick up the changes the next time the container is started.

This key should be sent as a header for most of the API calls:

Authorization: Bearer <my api key>

Request format

By default, the container listens on port 8080. Calls should follow call the URL: http://<server_address_or_IP>:8080/api/v1/relayers/<relayer_id>/rpc

relayer_id is the name given to a relayer configuration in ./config/config.json file.

Environments

Solana
EVM
Stellar

Common actions

These are a set of REST calls common to both Solana and EVM relayers.

We are assuming a base url of http://localhost:8080/ for these examples.

List relayers

Request: GET http://localhost:8080/api/v1/relayers/

Example request:

curl --location --request GET 'http://localhost:8080/api/v1/relayers/' \
--header 'Authorization: Bearer <my_api_key>'

Example response:

{
    "success": true,
    "data": [
        {
            "id": "sepolia-example",
            "name": "Sepolia Example",
            "network": "sepolia",
            "paused": false,
            "network_type": "evm",
            "signer_id": "local-signer",
            "policies": {
                "eip1559_pricing": false,
                "private_transactions": false,
                "min_balance": 1
            },
            "address": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
            "notification_id": "notification-example",
            "system_disabled": false
        }
    ],
    "error": null,
    "pagination": {
        "current_page": 1,
        "per_page": 10,
        "total_items": 1
    }
}

Get relayer details

Request: GET http://localhost:8080/api/v1/relayers/<relayer_id>;

relayer_id can be found by listing relayers or checking the config file (./config/config.json)

Example request:

curl --location --request GET 'http://localhost:8080/api/v1/relayers/<relayer_id>' \
--header 'Authorization: Bearer <my_api_key>'

Example response:

{
    "success": true,
    "data": {
        "id": "sepolia-example",
        "name": "Sepolia Example",
        "network": "sepolia",
        "network_type": "evm",
        "paused": false,
        "policies": {
            "eip1559_pricing": false,
            "private_transactions": false,
            "min_balance": 1
        },
        "address": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
        "system_disabled": false
    },
    "error": null
}

Update Relayer

Request: PATCH http://localhost:8080/api/v1/relayers/<relayer_id>;

Example request to pause a relayer:

curl --location --request PATCH 'http://localhost:8080/api/v1/relayers/<relayer_id>' \
--header 'Authorization: Bearer <my_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "paused": true
}'

Example response:

{
    "success": true,
    "data": {
        "id": "sepolia-example",
        "name": "Sepolia Example",
        "network": "sepolia",
        "paused": true,
        "network_type": "evm",
        "signer_id": "local-signer",
        "policies": {
            "eip1559_pricing": false,
            "private_transactions": false,
            "min_balance": 1
        },
        "address": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
        "notification_id": "notification-example",
        "system_disabled": false
    },
    "error": null
}

Get relayer balance

Request: GET http://localhost:8080/api/v1/relayers/<relayer_id>/balance

Example request to pause a relayer:

curl --location --request GET 'http://localhost:8080/api/v1/relayers/sepolia-example/balance' \
--header 'Authorization: Bearer <api_key>'

Example response:

{
    "success": true,
    "data": {
        "balance": 1000000000000000,
        "unit": "wei"
    },
    "error": null
}

Get relayer status

Request: GET http://localhost:8080/api/v1/relayers/<relayer_id>/status

Example request:

curl --location --request GET 'http://localhost:8080/api/v1/relayers/sepolia-example/status' \
--header 'Authorization: Bearer <api_key>'

Example response for EVM relayer:

{
    "success": true,
    "data": {
        "balance": "1000000000000000000",
        "pending_transactions_count": 2,
        "last_confirmed_transaction_timestamp": "2025-02-26T13:28:55.838812+00:00",
        "system_disabled": false,
        "paused": false,
        "nonce": "42"
    },
    "error": null
}

Example response for Stellar relayer:

{
    "success": true,
    "data": {
        "balance": "100000000",
        "pending_transactions_count": 0,
        "last_confirmed_transaction_timestamp": null,
        "system_disabled": false,
        "paused": false,
        "sequence_number": "12345678901234567890"
    },
    "error": null
}

Response fields:

Field Type Description

Field	Type	Description
`balance`	String	Current relayer balance in the smallest unit (wei for EVM, lamports for Solana, stroops for Stellar)
`pending_transactions_count`	Number	Number of transactions that are pending, submitted, or mined but not yet confirmed
`last_confirmed_transaction_timestamp`	String (optional)	ISO 8601 timestamp of the most recent confirmed transaction, or `null` if no transactions have been confirmed
`system_disabled`	Boolean	Whether the relayer has been disabled by the system due to errors or configuration issues
`paused`	Boolean	Whether the relayer has been manually paused
`nonce`	String (EVM only)	Current transaction nonce for EVM relayers
`sequence_number`	String (Stellar only)	Current sequence number for Stellar relayers

balance

String

Current relayer balance in the smallest unit (wei for EVM, lamports for Solana, stroops for Stellar)

pending_transactions_count

Number

Number of transactions that are pending, submitted, or mined but not yet confirmed

last_confirmed_transaction_timestamp

String (optional)

ISO 8601 timestamp of the most recent confirmed transaction, or null if no transactions have been confirmed

system_disabled

Boolean

Whether the relayer has been disabled by the system due to errors or configuration issues

paused

Boolean

Whether the relayer has been manually paused

nonce

String (EVM only)

Current transaction nonce for EVM relayers

sequence_number

String (Stellar only)

Current sequence number for Stellar relayers

For Solana relayers, this endpoint is currently not supported and will return an error
Network-specific fields (nonce for EVM, sequence_number for Stellar) are included directly in the response using JSON flattening
The balance field represents the raw balance value as a string to avoid precision loss with large numbers

Solana

The Solana API implementation conforms to the Paymaster Spec.

Solana API

Method Name Required Parameters Result Description

Method Name	Required Parameters	Result	Description
feeEstimate	`transaction`, `fee_token`	`estimated_fee`, `conversion_rate`	Estimate the fee for an arbitrary transaction using a specified token.
transferTransaction	`amount`, `token`, `source`, `destination`	`transaction`, `fee_in_spl`, `token`, `fee_in_lamports`, `valid_until_blockheight`	Create a transfer transaction for a specified token, sender, and recipient. The token supplied will be assumed to be the token to also be used for fees. Returns a partially signed transaction.
prepareTransaction	`transaction`, `fee_token`	`transaction`, `fee_in_spl`, `fee_token`, `fee_in_lamports`, `valid_until_blockheight`	Prepare a transaction by adding relayer-specific instructions. Returns a partially signed transaction.
signTransaction	`transaction`	`transaction`, `signature`	Sign a prepared transaction without submitting it to the blockchain.
signAndSendTransaction	`transaction`	`transaction`, `signature`	Sign and submit a transaction to the blockchain.
getSupportedTokens	(none)	`tokens[]` (list of token metadata)	Retrieve a list of tokens supported by the relayer for fee payments.
getFeaturesEnabled	(none)	`features[]` (list of enabled features)	Retrieve a list of features supported by the relayer.

feeEstimate

transaction, fee_token

estimated_fee, conversion_rate

Estimate the fee for an arbitrary transaction using a specified token.

transferTransaction

amount, token, source, destination

transaction, fee_in_spl, token, fee_in_lamports, valid_until_blockheight

Create a transfer transaction for a specified token, sender, and recipient. The token supplied will be assumed to be the token to also be used for fees. Returns a partially signed transaction.

prepareTransaction

transaction, fee_token

transaction, fee_in_spl, fee_token, fee_in_lamports, valid_until_blockheight

Prepare a transaction by adding relayer-specific instructions. Returns a partially signed transaction.

signTransaction

transaction

transaction, signature

Sign a prepared transaction without submitting it to the blockchain.

signAndSendTransaction

transaction

transaction, signature

Sign and submit a transaction to the blockchain.

getSupportedTokens

(none)

tokens[] (list of token metadata)

Retrieve a list of tokens supported by the relayer for fee payments.

getFeaturesEnabled

(none)

features[] (list of enabled features)

Retrieve a list of features supported by the relayer.

Key terminology

Key Description

Key	Description
`transaction`	Base64-encoded serialized Solana transaction. This could be a signed or unsigned transaction.
`signature`	Unique "transaction hash" that can be used to look up transaction status on-chain.
`source`	Source wallet address. The relayer is responsible for deriving and the TA.
`destination`	Destination wallet address. The relayer is responsible for deriving and creating the TA if necessary.
`fee_token`	Token mint address for the fee payment.
`fee_in_spl`	Fee amount the end user will pay to the relayer to process the transaction in spl tokens in the smallest unit of the spl token (no decimals)
`fee_in_lamports`	Fee amount in Lamports the Relayer estimates it will pay for the transaction.
`valid_until_block_height`	Expiration block height for time-sensitive operations.
`tokens[]`	Array of supported token metadata (e.g., symbol, mint, decimals).
`features[]`	Array of features enabled by the relayer (e.g., bundle support, sponsorship).

transaction

Base64-encoded serialized Solana transaction. This could be a signed or unsigned transaction.

signature

Unique "transaction hash" that can be used to look up transaction status on-chain.

source

Source wallet address. The relayer is responsible for deriving and the TA.

destination

Destination wallet address. The relayer is responsible for deriving and creating the TA if necessary.

fee_token

Token mint address for the fee payment.

fee_in_spl

Fee amount the end user will pay to the relayer to process the transaction in spl tokens in the smallest unit of the spl token (no decimals)

fee_in_lamports

Fee amount in Lamports the Relayer estimates it will pay for the transaction.

valid_until_block_height

Expiration block height for time-sensitive operations.

tokens[]

Array of supported token metadata (e.g., symbol, mint, decimals).

features[]

Array of features enabled by the relayer (e.g., bundle support, sponsorship).

We are assuming a base url of http://localhost:8080/ for these examples.

Get supported tokens

Request:

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<solana_relayer_id>/rpc' \
--header 'Authorization: Bearer <my_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "getSupportedTokens",
    "params": {},
    "id": 2
}'

Result:

{
    "jsonrpc": "2.0",
    "result": {
        "tokens": [
            {
                "decimals": 6,
                "max_allowed_fee": 100000000,
                "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                "symbol": "USDC"
            },
            {
                "decimals": 9,
                "max_allowed_fee": null,
                "mint": "So11111111111111111111111111111111111111112",
                "symbol": "SOL"
            }
        ]
    },
    "id": 2
}

Fee estimate

The fee estimation method returns mocked values on devnet and testnet because the Jupiter service is available only on mainnet-beta.

Request:

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<solana_relayer_id>/rpc' \
--header 'Authorization: Bearer <my_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "jsonrpc": "2.0",
  "method": "feeEstimate",
  "params": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZzDKeiaRTZZ3ipAtgJOOmqCGhz1iUHo8A9xynrbleugBAgIAAQwCAAAAQEIPAAAAAAA=",
    "fee_token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
  },
  "id": 3
}'

Result:

{
    "jsonrpc": "2.0",
    "result": {
        "conversion_rate": "142.6",
        "estimated_fee": "0.000713"
    },
    "id": 3
}

Sign transaction

Request:

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<solana_relayer_id>/rpc' \
--header 'Authorization: Bearer <my_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "method": "signTransaction",
  "params": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/bKmYrYtPWWI7zwiXWqAC5iFnkAkRL2D8s6lPkoJJokBAgIAAQwCAAAAQEIPAAAAAAA="

  },
  "id": 4
}'

Result:

{
    "jsonrpc": "2.0",
    "result": {
        "signature": "2jg9xbGLtZRsiJBrDWQnz33JuLjDkiKSZuxZPdjJ3qrJbMeTEerXFAKynkPW63J88nq63cvosDNRsg9VqHtGixvP",
        "transaction": "AVbRgFoUlj0XdlLP4gJJ2zwmr/2g2LOdeNqGPYTl4VFzY7lrX+nKNXUEU0DLJEA+2BW3uHvudQSXz5YBqd5d9gwBAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/bKmYrYtPWWI7zwiXWqAC5iFnkAkRL2D8s6lPkoJJokBAgIAAQwCAAAAQEIPAAAAAAA="
    },
    "id": 4
}

Sign and send transaction

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<solana_relayer_id>/rpc' \
--header 'Authorization: Bearer <my_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "method": "signAndSendTransaction",
  "params": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/bKmYrYtPWWI7zwiXWqAC5iFnkAkRL2D8s6lPkoJJokBAgIAAQwCAAAAQEIPAAAAAAA="
  },
  "id": 5
}'

Result:

{
    "jsonrpc": "2.0",
    "result": {
        "signature": "2jg9xbGLtZRsiJBrDWQnz33JuLjDkiKSZuxZPdjJ3qrJbMeTEerXFAKynkPW63J88nq63cvosDNRsg9VqHtGixvP",
        "transaction": "AVbRgFoUlj0XdlLP4gJJ2zwmr/2g2LOdeNqGPYTl4VFzY7lrX+nKNXUEU0DLJEA+2BW3uHvudQSXz5YBqd5d9gwBAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/bKmYrYtPWWI7zwiXWqAC5iFnkAkRL2D8s6lPkoJJokBAgIAAQwCAAAAQEIPAAAAAAA="
    },
    "id": 5
}

Prepare Transaction

The prepare transaction method returns a mocked value for the fee_in_spl response field on devnet and testnet, because the Jupiter service is available only on mainnet-beta.

curl --location --request POST 'http://localhost:8080/api/v1/relayers/solana-example/rpc' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "method": "prepareTransaction",
  "params": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/bKmYrYtPWWI7zwiXWqAC5iFnkAkRL2D8s6lPkoJJokBAgIAAQwCAAAAQEIPAAAAAAA=",
    "fee_token": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr"

  },
  "id": 6
}'

Result:

{
    "jsonrpc": "2.0",
    "result": {
        "fee_in_lamports": "5000",
        "fee_in_spl": "5000",
        "fee_token": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr",
        "transaction": "Ae7kEB+DOH8vhFDlV6SqTCcaf0mJI/Yrn1Zr/WFh8kEfdD0c99wJ1bYV3FDjt/qtwxRa5LxuVDlHR2CT+M5BIgYBAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAuTJfv3pxOOfvB3SHRW0ArtL0kkx6rVqN+d+tGrRgLIMBAgIAAQwCAAAAQEIPAAAAAAA=",
        "valid_until_blockheight": 351723643
    },
    "id": 6
}

Transfer Transaction

The transfer transaction method returns a mocked value for the fee_in_spl response field on devnet and testnet, because the Jupiter service is available only on mainnet-beta.

curl --location --request POST 'http://localhost:8080/api/v1/relayers/solana-example/rpc' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "method": "transferTransaction",
  "params": {
    "token": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr",
    "amount": 1,
    "source": "C6VBV1EK2Jx7kFgCkCD5wuDeQtEH8ct2hHGUPzEhUSc8",
    "destination": "D6VBV1EK2Jx7kFgCkCD5wuDeQtEH8ct2hHGUPzEhUSc8"

  },
  "id": 7
}'

Result:

{
    "jsonrpc": "2.0",
    "result": {
        "fee_in_lamports": "5000",
        "fee_in_spl": "5000",
        "fee_token": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr",
        "transaction": "AaQ8y7r1eIuwrmhuIWSJ7iWVJ5gAhZaZ9vd2I9wQ0PFs79GPYejdVrsVgMLm3t1c7g/WsoYhoPdt83ST1xcwdggBAAIEpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEMsnnyKbZZ5yUtDsJ/8r0KO7Li3BEwZoWs+nOJzoXwvgbd9uHXZaGT2cvhRs7reawctIXtX1s3kTqM9YV+/wCp6Sg5VQll/9TWSsqvRtRd9zGOW09XyQxIfWBiXYKbg3tDrlnF1KFvUS/T47LoVLV2lUyLS2zrfs8g57jdLLGvWwECBAEDAQAKDAEAAAAAAAAABg==",
        "valid_until_blockheight": 351724045
    },
    "id": 7
}

EVM

Method Required Parameters Result Description

Method	Required Parameters	Description
send transaction	`value`, `data`, `to`, `gas_limit`	Submit transaction to blockchain.
list transactions	(none)	List relayer transactions.
get transaction by id	`id`	Retrieve transaction by id.
get transaction by nonce	`nonce`	Retrieve transaction by nonce.

send transaction

value, data, to, gas_limit

Submit transaction to blockchain.

list transactions

(none)

List relayer transactions.

get transaction by id

id

Retrieve transaction by id.

get transaction by nonce

nonce

Retrieve transaction by nonce.

Send transaction

Request: POST http://localhost:8080/api/v1/relayers/<relayer_id>/transactions

Example request to send transaction:

 curl --location --request POST 'http://localhost:8080/api/v1/relayers/sepolia-example/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "value": 1,
    "data": "0x",
    "to": "0xd9b55a2ba539031e3c18c9528b0dc3a7f603a93b",
    "gas_limit": 21000,
    "speed": "average"
}'

Example response:

{
    "success": true,
    "data": {
        "id": "47f440b3-f4ce-4441-9489-55fc83be12cf",
        "hash": null,
        "status": "pending",
        "created_at": "2025-02-26T13:24:35.560593+00:00",
        "sent_at": null,
        "confirmed_at": null,
        "gas_price": null,
        "gas_limit": 21000,
        "nonce": 0,
        "value": "0x1",
        "from": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
        "to": "0x5e87fD270D40C47266B7E3c822f4a9d21043012D",
        "relayer_id": "sepolia-example"
    },
    "error": null
}

List Transactions

Request: GET http://localhost:8080/api/v1/relayers/<relayer_id>/transactions

Example request to list relayer transactions:

curl --location --request GET 'http://localhost:8080/api/v1/relayers/sepolia-example/transactions' \
--header 'Authorization: Bearer <api_key>'

Example response:

{
    "success": true,
     "data": [
        {
            "id": "bfa362dc-a84a-4466-93d0-b8487bfd40cc",
            "hash": "0xca349b67fad7b64239f4682a231c5398b0b52a93b626d1d67cb9ec037cdd290c",
            "status": "confirmed",
            "created_at": "2025-02-26T13:28:46.838812+00:00",
            "sent_at": "2025-02-26T13:28:48.838812+00:00",
            "confirmed_at": "2025-02-26T13:28:55.838812+00:00",
            "gas_price": 12312313123,
            "gas_limit": 21000,
            "nonce": 8,
            "value": "0x1",
            "from": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
            "to": "0x5e87fD270D40C47266B7E3c822f4a9d21043012D",
            "relayer_id": "sepolia-example"
        },
    ],
    "error": null,
    "pagination": {
        "current_page": 1,
        "per_page": 10,
        "total_items": 0
    }
}

Get transaction by id

Request: GET http://localhost:8080/api/v1/relayers/<relayer_id>/transactions/id

Example request fetch relayer transaction by id:

curl --location --request GET 'http://localhost:8080/api/v1/relayers/sepolia-example/transactions/47f440b3-f4ce-4441-9489-55fc83be12cf' \
--header 'Authorization: Bearer <api_key>'

Example response:

{
    "success": true,
    "data": {
        "id": "47f440b3-f4ce-4441-9489-55fc83be12cf",
        "hash": "0xa5759c99e99a1fc3b6e66bca75688659d583ee2556c7d185862dc8fcdaa4d5d7",
        "status": "confirmed",
        "created_at": "2025-02-26T13:28:46.838812+00:00",
        "sent_at": "2025-02-26T13:28:48.838812+00:00",
        "confirmed_at": "2025-02-26T13:28:55.838812+00:00",
        "gas_price": 35843464006,
        "gas_limit": 21000,
        "nonce": 0,
        "value": "0x1",
        "from": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
        "to": "0x5e87fD270D40C47266B7E3c822f4a9d21043012D",
        "relayer_id": "sepolia-example"
    },
    "error": null
}

Get transaction by nonce

Request: GET http://localhost:8080/api/v1/relayers/<relayer_id>/transactions/by-nonce/0

Example request fetch relayer transaction by nonce:

curl --location --request GET 'http://localhost:8080/api/v1/relayers/sepolia-example/transactions/by-nonce/0' \
--header 'Authorization: Bearer <api_key>'

Example response:

{
    "success": true,
    "data": {
        "id": "47f440b3-f4ce-4441-9489-55fc83be12cf",
        "hash": "0xa5759c99e99a1fc3b6e66bca75688659d583ee2556c7d185862dc8fcdaa4d5d7",
        "status": "confirmed",
        "created_at": "2025-02-26T13:28:46.838812+00:00",
        "sent_at": "2025-02-26T13:28:48.838812+00:00",
        "confirmed_at": "2025-02-26T13:28:55.838812+00:00",
        "gas_price": 35843464006,
        "gas_limit": 21000,
        "nonce": 0,
        "value": "0x1",
        "from": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
        "to": "0x5e87fD270D40C47266B7E3c822f4a9d21043012D",
        "relayer_id": "sepolia-example"
    },
    "error": null
}

Stellar

Basic support for Stellar; it is currently under active development. The API interactions and specifics described below may evolve.

This section outlines how to interact with the Stellar network via the Relayer API. The relayer supports Soroban smart contract operations, including contract invocation, deployment, and WASM uploads.

Method Name Required Parameters Description

Method Name	Required Parameters	Description
Send Transaction	`network`, `operations` (or `transaction_xdr`)	Submit a transaction to the Stellar network. Supports payment and InvokeHostFunction operations, pre-built XDR transactions, and fee bump transactions.
Get Transaction Details	`transaction_id`	Retrieve a specific transaction by its ID.
List Transactions	(none)	List transactions for the relayer.

Send Transaction

network, operations (or transaction_xdr)

Submit a transaction to the Stellar network. Supports payment and InvokeHostFunction operations, pre-built XDR transactions, and fee bump transactions.

Get Transaction Details

transaction_id

Retrieve a specific transaction by its ID.

List Transactions

(none)

List transactions for the relayer.

Supported Operation Types

Operation Type Description

Operation Type	Description
`payment`	Transfer native XLM or other assets between accounts
`invoke_contract`	Call a deployed Soroban smart contract function
`create_contract`	Deploy a new Soroban smart contract from WASM hash
`upload_wasm`	Upload WASM contract code to the Stellar ledger

payment

Transfer native XLM or other assets between accounts

invoke_contract

Call a deployed Soroban smart contract function

create_contract

Deploy a new Soroban smart contract from WASM hash

upload_wasm

Upload WASM contract code to the Stellar ledger

Send Transaction

Submit a transaction to the Stellar network.

Request: POST http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions

Transaction Input Methods

The relayer supports three ways to submit transactions:

Operations-based: Build a transaction by specifying the operations array (recommended for most use cases)
Transaction XDR (unsigned): Submit a pre-built unsigned transaction using transaction_xdr field (advanced use case)
Transaction XDR (signed) with fee bump: Submit a signed transaction using transaction_xdr with fee_bump: true to wrap it in a fee bump transaction ===== Transaction Structure

Required fields: - network: The Stellar network ("testnet", "mainnet", etc.) - Either operations (array of operations) OR transaction_xdr (base64-encoded XDR) - but not both

Optional fields: - source_account: The Stellar account that will be the source of the transaction (defaults to relayer’s address) - memo: Transaction memo (see Memo Types below) - valid_until: Transaction expiration time (ISO 8601 format) - transaction_xdr: Pre-built transaction XDR (base64 encoded, signed or unsigned) - mutually exclusive with operations - fee_bump: Boolean flag to request fee-bump wrapper (only valid with signed transaction_xdr) - max_fee: Maximum fee for fee bump transactions in stroops (defaults to 1,000,000 = 0.1 XLM)

Asset Types

Assets in Stellar operations must be specified with a type field:

Native XLM:

{"type": "native"}

Credit Asset (4 characters or less):

{
  "type": "credit_alphanum4",
  "code": "USDC",
  "issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

Credit Asset (5-12 characters):

{
  "type": "credit_alphanum12",
  "code": "LONGASSET",
  "issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

Memo Types

Transactions can include optional memos:

No Memo:

{"type": "none"}

Text Memo (max 28 UTF-8 bytes):

{"type": "text", "value": "Payment for services"}

ID Memo:

{"type": "id", "value": "12345"}

Hash Memo (32 bytes hex):

{"type": "hash", "value": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"}

Return Memo (32 bytes hex):

{"type": "return", "value": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"}

Example requests (cURL):

1. Payment Operation:

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "operations": [
    {
      "type": "payment",
      "destination": "GD77B6LYQ5XDCW6CND7CQMA23FSV7MZQGLBAU5OMEOXQM6XFTCMWQQCJ",
      "asset": {"type": "native"},
      "amount": 1000000
    }
  ],
  "memo": {"type": "text", "value": "Payment for services"}
}'

2. Invoke Contract:

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "operations": [
    {
      "type": "invoke_contract",
      "contract_address": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJUWDA",
      "function_name": "transfer",
      "args": [
        {"address": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY"},
        {"address": "GD77B6LYQ5XDCW6CND7CQMA23FSV7MZQGLBAU5OMEOXQM6XFTCMWQQCJ"},
        {"u64": "1000000"}
      ],
      "auth": {"type": "source_account"}
    }
  ]
}'

3. Create Contract:

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "operations": [
    {
      "type": "create_contract",
      "source": {
        "from": "address",
        "address": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY"
      },
      "wasm_hash": "d3b2f6f8a1c5e9b4a7d8c2e1f5a9b3c6e8d4f7a2b5c8e1d4f7a0b3c6e9d2f5a8",
      "salt": "0000000000000000000000000000000000000000000000000000000000000001"
    }
  ]
}'

For create_contract, you can also include optional constructor_args array and use "from": "contract" for factory pattern deployments.

4. Upload WASM:

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "operations": [
    {
      "type": "upload_wasm",
      "wasm": {
        "type": "base64",
        "base64": "AGFzbQEAAAABBgFgAX8BfwMCAQAFAwEAAQcPAgVoZWxsbwAACG1lbW9yeTIDCgQAAAAL"
      }
    }
  ]
}'

WASM can be provided as either "type": "base64" or "type": "hex" encoding.

5. Submit Pre-built Unsigned Transaction (XDR):

For advanced use cases, you can submit a pre-built unsigned transaction as base64-encoded XDR:

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "transaction_xdr": "AAAAAgAAAAC0V9YG9Ks6MEexw5yB+FDD8VJwmtv5OU2BwgPN6PpZcwAAAGQCeO4pAAAAAgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAACgAAAAAAAAAAAAAAAAAAAAA=",
  "source_account": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY"
}'

When submitting XDR transactions, the operations field is not required. The relayer will parse the transaction from the XDR

6. Fee Bump Transaction:

To submit a fee bump transaction for an existing signed transaction:

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "transaction_xdr": "AAAAAgAAAAC0V9YG9Ks6MEexw5yB+FDD8VJwmtv5OU2BwgPN6PpZcwAAAGQCeO4pAAAAAgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAACgAAAAAAAAAAAAAAAAAAAADN6PpZcwAAAEDtHqNhqC0V8mEZX9xXd4Gw3amGyg/aNTPKUQIH2nipnRps7H3HQTPhPiSzxwvzfXcGAz9H3hXXIkWegqJlEAoN",
  "fee_bump": true,
  "max_fee": 1000000
}'

When fee_bump is true, the transaction_xdr should contain a fully signed transaction (not a fee bump envelope). The relayer will create a fee bump transaction wrapper around it, paying the additional fees up to max_fee (in stroops).

Example response:

{
  "success": true,
  "data": {
    "id": "5431b88c-183b-41c7-9bbb-841d38ddd866",
    "hash": null,
    "status": "pending",
    "created_at": "2025-05-19T11:26:55.188781+00:00",
    "sent_at": null,
    "confirmed_at": null,
    "source_account": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY",
    "fee": 0,
    "sequence_number": 0
  },
  "error": null
}

Get Transaction Details

Retrieve details for a specific Stellar transaction submitted via the relayer.

Request: GET http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions/<transaction_id>;

<stellar_relayer_id>: The ID of your Stellar relayer configuration.
<transaction_id>: The ID of the transaction (returned from Send Transaction or from List Transactions).

Example request (cURL):

curl --location --request GET 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions/<transaction_id_example>' \
--header 'Authorization: Bearer <your_api_key>'

Example response:

{
    "success": true,
    "data": {
        "id": "5431b88c-183b-41c7-9bbb-841d38ddd866",
        "hash": "f22e5d9a36cbedee20de01d5bf89d2e80682c102e844d72f567da1acd1944cb0",
        "status": "submitted",
        "created_at": "2025-05-19T11:26:55.188781+00:00",
        "sent_at": "2025-05-19T11:26:56.136646+00:00",
        "confirmed_at": null,
        "source_account": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY",
        "fee": 0,
        "sequence_number": 3700719915892739
    },
    "error": null
}

List Transactions

List transactions associated with a Stellar relayer, with support for pagination.

Request: GET http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions

Example request (cURL):

curl --location --request GET 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <your_api_key>'

Example response:

{
    "success": true,
    "data": [
        {
            "id": "5431b88c-183b-41c7-9bbb-841d38ddd866",
            "hash": "f22e5d9a36cbedee20de01d5bf89d2e80682c102e844d72f567da1acd1944cb0",
            "status": "submitted",
            "created_at": "2025-05-19T11:26:55.188781+00:00",
            "sent_at": "2025-05-19T11:26:56.136646+00:00",
            "confirmed_at": null,
            "source_account": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY",
            "fee": 0,
            "sequence_number": 3700719915892739
        }
    ],
    "error": null,
    "pagination": {
        "current_page": 1,
        "per_page": 10,
        "total_items": 1
    }
}

ScVal Argument Format

When invoking contract functions, arguments must be provided as ScVal values in JSON format. The relayer uses the stellar-xdr JSON serialization format.

Here are the supported ScVal types and their formats:

Type Format Description

Type	Format	Description
U64	`{"u64": "1000000"}`	Unsigned 64-bit integer
I64	`{"i64": "-500"}`	Signed 64-bit integer
U32	`{"u32": 42}`	Unsigned 32-bit integer
I32	`{"i32": -42}`	Signed 32-bit integer
Boolean	`{"bool": true}`	Boolean value
String	`{"string": "hello world"}`	UTF-8 string
Symbol	`{"symbol": "transfer"}`	Symbol (used for function names and identifiers)
Address	`{"address": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY"}`	Stellar account or contract address
Bytes	`{"bytes": "deadbeef"}`	Hex-encoded byte array
Vector	`{"vec": [{"u32": 1}, {"u32": 2}, {"u32": 3}]}`	Array of ScVal values
Map	`{"map": [{"key": {"symbol": "name"}, "val": {"string": "MyToken"}}]}`	Key-value pairs of ScVal values
U128	`{"u128": {"hi": "100", "lo": "200"}}`	Unsigned 128-bit integer (as high/low parts)
I128	`{"i128": {"hi": "-100", "lo": "200"}}`	Signed 128-bit integer (as high/low parts)
U256	`{"u256": {"hi_hi": "1", "hi_lo": "2", "lo_hi": "3", "lo_lo": "4"}}`	Unsigned 256-bit integer (as four 64-bit parts)
I256	`{"i256": {"hi_hi": "-1", "hi_lo": "2", "lo_hi": "3", "lo_lo": "4"}}`	Signed 256-bit integer (as four 64-bit parts)

U64

{"u64": "1000000"}

Unsigned 64-bit integer

I64

{"i64": "-500"}

Signed 64-bit integer

U32

{"u32": 42}

Unsigned 32-bit integer

I32

{"i32": -42}

Signed 32-bit integer

Boolean

{"bool": true}

Boolean value

String

{"string": "hello world"}

UTF-8 string

Symbol

{"symbol": "transfer"}

Symbol (used for function names and identifiers)

Address

{"address": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY"}

Stellar account or contract address

Bytes

{"bytes": "deadbeef"}

Hex-encoded byte array

Vector

{"vec": [{"u32": 1}, {"u32": 2}, {"u32": 3}]}

Array of ScVal values

Map

{"map": [{"key": {"symbol": "name"}, "val": {"string": "MyToken"}}]}

Key-value pairs of ScVal values

U128

{"u128": {"hi": "100", "lo": "200"}}

Unsigned 128-bit integer (as high/low parts)

I128

{"i128": {"hi": "-100", "lo": "200"}}

Signed 128-bit integer (as high/low parts)

U256

{"u256": {"hi_hi": "1", "hi_lo": "2", "lo_hi": "3", "lo_lo": "4"}}

Unsigned 256-bit integer (as four 64-bit parts)

I256

{"i256": {"hi_hi": "-1", "hi_lo": "2", "lo_hi": "3", "lo_lo": "4"}}

Signed 256-bit integer (as four 64-bit parts)

Address Format Notes: - Account addresses start with 'G' - Contract addresses start with 'C' - All addresses use SEP-23 Strkey encoding

Authorization Modes

Soroban operations support different authorization modes:

Type Description Example Usage

Type	Description	Example Usage
`none`	No authorization required	`"auth": {"type": "none"}`
`source_account`	Use the transaction source account (default)	`"auth": {"type": "source_account"}`
`addresses`	Use specific addresses (future feature)	`"auth": {"type": "addresses", "signers": ["GABC…"]}`
`xdr`	Advanced: provide base64-encoded XDR entries	`"auth": {"type": "xdr", "entries": ["<base64>"]}`

none

No authorization required

"auth": {"type": "none"}

source_account

Use the transaction source account (default)

"auth": {"type": "source_account"}

addresses

Use specific addresses (future feature)

"auth": {"type": "addresses", "signers": ["GABC…"]}

xdr

Advanced: provide base64-encoded XDR entries

"auth": {"type": "xdr", "entries": ["<base64>"]}