> ## Documentation Index > Fetch the complete documentation index at: https://docs.buckspay.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Relay a signed payment > Submit a signed Soroban `SorobanAuthorizationEntry` (base64 XDR) to the facilitator. The facilitator wraps it in a fee-bump transaction, submits it to Stellar, and returns a `Receipt`. In gas-in-token mode, set `feeToken` and ensure `authorizationEntryXdr` encodes the `FeeForwarder.forward()` invocation (a single host-function op that includes the actual transfer as a sub-invocation). No separate fee auth entry is needed. **The API key is injected server-side by the BFF; the browser never sends this header directly.** ## OpenAPI ````yaml /api-reference/openapi.json post /relay openapi: 3.1.0 info: title: Buckspay Facilitator & BFF API version: 0.2.0 description: >- HTTP wire contract for the Buckspay SDK. The SDK calls these endpoints internally via `@buckspay/relayer`; this reference is for teams building their own BFF relay route or calling the facilitator from server-side code. All facilitator endpoints require the `x-api-key` header. **The API key is a server-side secret - it must only appear in BFF or server-side code and must never be shipped to a browser bundle.** Use `createRelayRoute` and `createSignerProxyRoute` from `@buckspay/nextjs` to build compliant BFF handlers. servers: - url: '{facilitatorUrl}' description: >- Buckspay facilitator (all endpoints). Set via BUCKSPAY_FACILITATOR_URL on the server. variables: facilitatorUrl: default: https://facilitator.buckspay.xyz description: Base URL of the Buckspay facilitator service. security: - FacilitatorApiKey: [] tags: - name: Relay description: >- Submit a signed Soroban authorization entry for gasless relaying to the Stellar network. - name: Fee description: >- Quote the fee-token amount required for gas-in-token (token gas mode) before building the forward() invocation. - name: Account State description: Read on-chain state for classic G-addresses and contract C-addresses. - name: Onboarding description: >- Build and submit the sponsored onboarding transaction; deploy passkey smart-accounts and policy session-accounts. - name: Auth description: >- Signer-proxy for social and email authentication. The BFF forwards these requests to the facilitator; provider secrets remain server-side. - name: Swap description: >- Quote a gasless EVM token swap. Requires `swapChain` to be configured in the relayer. paths: /relay: post: tags: - Relay summary: Relay a signed payment description: >- Submit a signed Soroban `SorobanAuthorizationEntry` (base64 XDR) to the facilitator. The facilitator wraps it in a fee-bump transaction, submits it to Stellar, and returns a `Receipt`. In gas-in-token mode, set `feeToken` and ensure `authorizationEntryXdr` encodes the `FeeForwarder.forward()` invocation (a single host-function op that includes the actual transfer as a sub-invocation). No separate fee auth entry is needed. **The API key is injected server-side by the BFF; the browser never sends this header directly.** operationId: postRelay requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RelayPayload' responses: '200': description: Payment relayed successfully. content: application/json: schema: $ref: '#/components/schemas/Receipt' '400': description: >- The payload was rejected by the facilitator. The `error` field contains the machine-readable code. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: session_policy_violation: summary: Session spend limit exceeded value: error: session_policy_violation message: transfer exceeds session spend limit auth_expired: summary: Authorization entry expired value: error: auth_expired message: signatureExpirationLedger is in the past simulation_failed: summary: Soroban simulation failed value: error: simulation_failed message: soroban simulation rejected the invocation tx_reverted: summary: Transaction reverted on-chain value: error: tx_reverted message: transaction was submitted but reverted recipient_not_allowed: summary: Recipient address not on allowlist value: error: recipient_not_allowed message: recipient is not in the session allowlist invalid_payload: summary: Payload failed schema validation value: error: invalid_payload '401': description: Invalid or missing API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: unauthorized '502': description: >- Facilitator could not reach Stellar Horizon or the submission failed infrastructure-side. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: horizon_unreachable: value: error: horizon_unreachable submission_failed: value: error: submission_failed components: schemas: RelayPayload: type: object required: - token - from - to - value - authorizationEntryXdr - nonce - signatureExpirationLedger properties: token: allOf: - $ref: '#/components/schemas/StellarContractAddress' description: USDC SAC contract address (C-address). The asset being transferred. from: allOf: - $ref: '#/components/schemas/StellarAddress' description: >- Payer address - either a classic G-address or a smart-contract C-address. to: allOf: - $ref: '#/components/schemas/StellarPublicKey' description: Recipient G-address. value: allOf: - $ref: '#/components/schemas/Stroops' description: Transfer amount in USDC stroops (7 decimal places). authorizationEntryXdr: allOf: - $ref: '#/components/schemas/Base64' description: >- 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. nonce: allOf: - $ref: '#/components/schemas/Stroops' description: >- Authorization nonce as a decimal string. Must match the nonce used when building the unsigned entry. signatureExpirationLedger: type: integer minimum: 1 description: >- Ledger sequence number after which the authorization entry is invalid. Must be in the future when the facilitator processes the request. feeToken: allOf: - $ref: '#/components/schemas/StellarContractAddress' description: >- 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). sessionOp: type: string enum: - install - revoke description: >- 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. description: >- Signed relay request. Mirrors the SDK `RelayPayload` type from `@buckspay/core`. Receipt: type: object required: - ok - via - token - chain - transferTx - status properties: ok: type: boolean description: Always `true` on a 200 response. via: type: string description: Relay strategy identifier (e.g. `buckspay_self`). token: type: string description: Contract address of the transferred token. chain: type: string enum: - stellar-testnet - stellar-pubnet - avalanche - celo - polygon - base - avalanche-fuji - polygon-amoy - base-sepolia - celo-sepolia description: Chain on which the transaction was submitted. transferTx: type: string minLength: 1 description: Transaction hash or identifier of the submitted transaction. ledger: type: integer minimum: 0 description: >- Ledger sequence number at which the transaction was included. Absent if the facilitator did not return a ledger (omitted, not null). status: type: string description: Human-readable status string from the facilitator (e.g. `SUCCESS`). description: >- 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`. ErrorResponse: type: object required: - error properties: error: type: string description: >- Machine-readable error code. SDK error codes (e.g. `RELAYER_REJECTED`, `SESSION_POLICY_VIOLATION`) or raw facilitator codes (e.g. `auth_expired`, `simulation_failed`) depending on context. message: type: string description: >- Optional human-readable detail. Never log raw upstream messages - they may contain addresses or sensitive information. details: type: object description: >- Optional structured validation errors (present on BFF-level schema failures). description: >- Error body returned on non-2xx responses. The `error` field maps to a `BuckspayErrorCode` or a raw facilitator error string (see `mapFacilitatorError` in `@buckspay/relayer`). StellarContractAddress: type: string pattern: ^C[A-Z2-7]{55}$ description: Stellar contract address (C-address, 56-character StrKey). StellarAddress: type: string pattern: ^[GC][A-Z2-7]{55}$ description: 'Stellar address: either a classic G-address or a contract C-address.' StellarPublicKey: type: string pattern: ^G[A-Z2-7]{55}$ description: Stellar classic public key (G-address, 56-character StrKey). Stroops: type: string pattern: ^\d+$ description: >- A non-negative integer encoded as a decimal string to preserve precision. For Stellar token amounts this is the smallest unit with the asset's implied decimals (USDC = 7, i.e. stroops); the same string encoding also carries fees, nonces, and EVM swap amounts (which use their own token's decimals). Base64: type: string pattern: ^[A-Za-z0-9+/]+=*$ minLength: 1 description: Standard base64-encoded bytes. securitySchemes: FacilitatorApiKey: type: apiKey in: header name: x-api-key description: >- 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. ````