Skip to main content
GET
Get swap quote

Authorizations

x-api-key
string
header
required

API key for authentication. Obtain from your Pods dashboard.

Query Parameters

settlementMode
enum<string>

Bind provider instructions to the customer wallet (direct) or reserved workflow Safe (depositAddress). Use the same mode for bytecode acceptance. Omission preserves automatic behavior.

Available options:
direct,
depositAddress
Example:

"depositAddress"

originChain
string

Origin blockchain network name. Use with destinationChain.

Example:

"ethereum"

chainIdIn
number

Origin chain ID. Alternative to originChain.

Example:

1

destinationChain
string

Destination blockchain network name. Use with originChain.

Example:

"polygon"

chainIdOut
number

Destination chain ID. Alternative to destinationChain.

Example:

137

tokenIn
string
required

Input token contract address

Example:

"0xb794F5eA0ba39494cE839613fffBA74279579268"

tokenOut
string
required

Output token contract address

Example:

"0xb794F5eA0ba39494cE839613fffBA74279579268"

amountIn
string

Input amount in token smallest unit. USD onramp: USD cents. USD offramp: USDC raw (6 decimals). Provide either amountIn or amountOut, not both.

Example:

"1000000000000000000"

amountOut
string

Desired output amount in token smallest unit. USD onramp: USDC raw (6 decimals). USD offramp: USD cents. Provide either amountIn or amountOut, not both.

Example:

"1000000000000000000"

destinationAddress
string

Recipient on the destination chain (checksummed EVM or Solana public key). Omit for quote-only requests; use pixKey instead for fiat destinations.

Example:

"EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj"

pixKey
string

PIX key for BRL fiat off-ramp destinations. Use instead of destinationAddress when destinationChain is fiat and tokenOut is BRL. Only an explicitly supplied pixKey on a crypto-to-BRL fiat off-ramp is validated with Avenia. Invalid or unknown keys return INVALID_PIX_KEY (400). Pricing-only quotes may continue when lookup is unavailable. Explicit Avenia HTTP 5xx responses also allow executable output; other lookup failures block executable output with PIX_KEY_LOOKUP_FAILED (502).

alias
string

USD beneficiary alias. Defaults to bankBeneficiaryName when omitted. Used with bank account fields to resolve-or-create the Avenia beneficiary on quote.

Example:

"Payroll ACH"

bankAccountNumber
string

USD bank account number for USDC→USD offramp. Required with the other bank fields for USD offramp destinations.

Example:

"123456789"

bankRoutingNumber
string

USD ABA routing number for USDC→USD offramp.

Example:

"021000021"

bankBeneficiaryName
string

Legal name on the USD bank account. ASCII only — Avenia rejects accents (ã, é, …) with bankBeneficiaryName is invalid.

Example:

"John Smith"

bankName
string

Bank name for the USD beneficiary.

Example:

"Chase"

beneficiaryStreetLine1
string

Beneficiary street address line 1.

Example:

"1 Main St"

beneficiaryStreetLine2
string

Beneficiary street address line 2 (optional).

beneficiaryCity
string

Beneficiary city.

Example:

"New York"

beneficiaryState
string

Beneficiary state / province.

Example:

"NY"

beneficiaryPostalCode
string

Beneficiary postal code.

Example:

"10001"

beneficiaryCountry
string

Beneficiary country (ISO-style code as accepted by Avenia).

Example:

"USA"

description
string

Optional Avenia beneficiary description.

usdPaymentMethod
enum<string>

USD payment rail for foreign USD onramp/offramp. Defaults to WIRE when omitted.

Available options:
ACH,
WIRE
Example:

"WIRE"

thirdParty
boolean
default:false

Set to true for PIX off-ramp quotes paid to a third party. The value must match the bytecode request.

Example:

false

originAddress
string

Sender address on the origin chain (checksummed EVM or Solana public key). When provided with destinationAddress, pixKey, or USD bank account fields, the response also includes executable payload fields.

Example:

"EXYhCNamLPFfSMekSn7Lzc2cP32aZpRa7ok5gErdJzcj"

refundAddress
string

Address for refunds if swap fails

Example:

"0xb794F5eA0ba39494cE839613fffBA74279579268"

output
enum<string>
default:bytecode

Response format when both originAddress and destinationAddress are provided. Defaults to bytecode. userOperation and fireblocks are EVM-origin only. instructions is Solana-origin only.

Available options:
bytecode,
userOperation,
fireblocks,
instructions
accountId
string

Fireblocks vault account ID. Required when output=fireblocks.

Example:

"12"

feeSponsorship
boolean

The customer pays the Pods fee for this quote: no Pods slice is deducted from the user, and the waived amount is invoiced to the customer at month end. On aggregator swaps and Pix ramps the Pods base fee is waived; on routes priced through the orderbook the FX spread is waived too. The customer markup is still charged. Requires fee sponsorship to be enabled for the customer (403 FEE_SPONSORSHIP_NOT_ALLOWED).

Example:

false

markupBps
string

Customer markup for this quote in bps of the chargeable amount (amount-in on swaps, the USDC leg on ramps), replacing the configured markup. Integer up to 5000. Applies to aggregator swaps (1inch, LiFi, Relay, Uniswap, Jupiter) quoted by amountIn and to USDC fiat ramps (Pix and USD ACH/wire, onramp and offramp, on every rampProvider). A positive value requires a configured customer fee collector for the operation (422 MARKUP_RECIPIENT_NOT_CONFIGURED); values above 5000 return 422 MARKUP_BPS_ABOVE_MAX. A negative value absorbs that part of the Pods fee on aggregator swaps and on Pix ramps via BRLA: the user pays the Pods fee minus it (never below zero), no customer fee is transferred, the absorbed part is invoiced to the customer, and the fee breakdown shows a signed customer line. Negative values require fee sponsorship to be enabled for the customer (403 FEE_SPONSORSHIP_NOT_ALLOWED), cannot go below minus the Pods fee rate (422 MARKUP_BPS_BELOW_FLOOR, details.floorBps), cannot be combined with feeSponsorship (422 MARKUP_SPONSORSHIP_CONFLICT), and return 422 MARKUP_BPS_BELOW_FLOOR on USD ACH/wire and direct Pix ramps, which transfer each fee slice on its own. An amountOut aggregator swap charges no platform fee, so it cannot apply it; routes that cannot apply it (no platform fee split) are left out of ranking, and 422 MARKUP_OVERRIDE_NOT_ALLOWED is returned only when no eligible route can apply it or the requested preferredProvider cannot.

Example:

"40"

preferredProvider
string

Registered provider name to force when eligible for the route

Example:

"relay"

rampProvider
string

Fiat rail provider pin for onramp/offramp quotes. Omitted or empty defaults to avenia even when extraRampProviders includes unblockpay. The response returns this name as provider and omits rampProvider. Ignored on crypto-only quotes. Distinct from preferredProvider.

Example:

"avenia"

slippage
string

Slippage tolerance as a fraction of 1. Valid range is 0.0001 to 0.5.

Example:

"0.01"

transferSpeed
enum<string>

Transfer speed for CCTP cross-chain swaps

Available options:
fast,
standard
Example:

"fast"

webhookURL
string<uri>

Optional per-quote webhook endpoint. When set, ACTION_UPDATE webhooks for this quote are delivered to this URL instead of the customer default webhookURL. See the Webhooks guide.

Example:

"https://example.com/webhooks/swap-quote"

Response

Quote generated successfully

quote
object
required

Freshly generated swap quote returned by GET /v2/swap/quote

id
string

Action ID for execution tracking when bytecode is included

chainId
number

Origin chain ID when bytecode is included

transactionData
object

Transaction data for execution

userOperation
any | null

ERC-4337 user operation when output=userOperation and both addresses are provided

instructions
null[]

Solana instructions when output=instructions (Solana-origin only)

lutsByAddress
any | null

Solana lookup tables keyed by address when output=instructions