Skip to main content
POST
/
swap
/
quote
Error
A valid request URL is required to generate request examples
{
  "quoteId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sellAmount": "<string>",
  "expectedBuyAmount": "<string>",
  "minBuyAmount": "<string>",
  "typedData": "<string>",
  "needsAuthorization": true,
  "source": "<string>",
  "expiresAt": "<string>"
}

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

Request body for POST /swap/quote. Corresponds to the body built in buckspayFacilitator.quoteSwap().

​
chain
enum<string>
required

EVM chain for the swap. Must match the swapChain configured in buckspayFacilitator.

Available options:
avalanche,
celo,
polygon,
base,
avalanche-fuji,
polygon-amoy,
base-sepolia,
celo-sepolia
​
payer
string
required

EVM address of the payer (0x-prefixed).

​
merchant
string
required

EVM address where the buy-token is settled. For self-custody swaps this equals payer.

​
sellToken
string
required

EVM contract address of the sell token.

​
buyToken
string
required

EVM contract address of the buy token.

​
sellAmount
string
required

Amount to sell in the sell token's minimal units, as a decimal string.

Pattern: ^\d+$

Response

Swap quote computed.

Swap quote returned by POST /swap/quote. Mirrors the swapQuoteResponseSchema zod schema in @buckspay/relayer.

​
quoteId
string<uuid>
required

Unique identifier for this quote.

​
sellAmount
string
required

Actual sell amount (may differ from requested amount after routing).

Pattern: ^\d+$
​
expectedBuyAmount
string
required

Expected amount of buy token received.

Pattern: ^\d+$
​
minBuyAmount
string
required

Minimum buy amount after slippage. The client enforces this floor before submitting.

Pattern: ^\d+$
​
typedData
string
required

EIP-712 typed data string for the swap authorization. Required if needsAuthorization is true.

​
needsAuthorization
boolean
required

Whether the payer must sign the EIP-712 typedData before submitting the swap.

​
source
string
required

Liquidity source or aggregator used to build the quote.

​
expiresAt
string
required

ISO 8601 timestamp after which the quote is invalid.