Skip to main content
POST
/
relay
Error
A valid request URL is required to generate request examples
{
  "ok": true,
  "via": "<string>",
  "token": "<string>",
  "transferTx": "<string>",
  "status": "<string>",
  "ledger": 1
}

Authorizations

​
x-api-key
string
header
required

Server-held API key. Injected by the BFF (createRelayRoute / createSignerProxyRoute from @buckspay/nextjs). This key must only appear in server-side code and must never be shipped to a browser bundle.

Body

application/json

Signed relay request. Mirrors the SDK RelayPayload type from @buckspay/core.

​
token
string
required

USDC SAC contract address (C-address). The asset being transferred.

Pattern: ^C[A-Z2-7]{55}$
​
from
string
required

Payer address - either a classic G-address or a smart-contract C-address.

Pattern: ^[GC][A-Z2-7]{55}$
​
to
string
required

Recipient G-address.

Pattern: ^G[A-Z2-7]{55}$
​
value
string
required

Transfer amount in USDC stroops (7 decimal places).

Pattern: ^\d+$
​
authorizationEntryXdr
string
required

Signed SorobanAuthorizationEntry as base64 XDR. In gas-in-token mode this is the FeeForwarder.forward() entry; in sponsored mode it is the USDC transfer entry.

Minimum string length: 1
Pattern: ^[A-Za-z0-9+/]+=*$
​
nonce
string
required

Authorization nonce as a decimal string. Must match the nonce used when building the unsigned entry.

Pattern: ^\d+$
​
signatureExpirationLedger
integer
required

Ledger sequence number after which the authorization entry is invalid. Must be in the future when the facilitator processes the request.

Required range: x >= 1
​
feeToken
string

Optional. Present only in gas-in-token mode. Names the token used to pay the gas fee. When set, authorizationEntryXdr encodes the FeeForwarder.forward() invocation (not a bare transfer).

Pattern: ^C[A-Z2-7]{55}$
​
sessionOp
enum<string>

Optional. Marks the relay as a session management operation (install grants a new session key; revoke removes one). The facilitator relays it as a self-administered contract call on the policy account. Absent for ordinary USDC transfers.

Available options:
install,
revoke

Response

Payment relayed successfully.

Relay receipt returned by POST /relay. Mirrors the SDK Receipt type from @buckspay/core. The SDK adapter maps the facilitator's blockNumber field to ledger.

​
ok
boolean
required

Always true on a 200 response.

​
via
string
required

Relay strategy identifier (e.g. buckspay_self).

​
token
string
required

Contract address of the transferred token.

​
chain
enum<string>
required

Chain on which the transaction was submitted.

Available options:
stellar-testnet,
stellar-pubnet,
avalanche,
celo,
polygon,
base,
avalanche-fuji,
polygon-amoy,
base-sepolia,
celo-sepolia
​
transferTx
string
required

Transaction hash or identifier of the submitted transaction.

Minimum string length: 1
​
status
string
required

Human-readable status string from the facilitator (e.g. SUCCESS).

​
ledger
integer

Ledger sequence number at which the transaction was included. Absent if the facilitator did not return a ledger (omitted, not null).

Required range: x >= 0