Skip to main content
Pods Ramp moves money between a local fiat rail and an on-chain asset. Every pair — Brazil Pix and foreign USD wire are live today; Mexico, Colombia, and Argentina use the same routes once live — goes through a single endpoint: GET /v2/swap/quote. Money-movement routes are available only after Ramp status is approved. See KYC setup guide and Track Pods Ramp status.
Send every request from your backend with x-api-key. Never expose PODS_API_KEY to a browser or mobile client.

How ramp quotes work

A quote is defined by four query parameters. originChain and destinationChain set the source and destination networks; fiat on either side selects the local payment rail. tokenIn and tokenOut set the fiat currency or on-chain asset. The direction follows from which side is fiat: originChain=fiat is an onramp, destinationChain=fiat is an offramp.
1

Request a quote

Call GET /v2/swap/quote. On onramps pass destinationAddress (the wallet that receives crypto). On offramps pass originAddress plus the payout target (pixKey for Pix, or the USD bank fields).
2

Act on the response

  • Onramp — the response carries paymentInstructions (transactionData is [], chainId is null). Show the local rail: paymentInstructions.pix.copyPaste for Pix, or paymentInstructions.usd bank fields for a USD wire.
  • Offramp — the response carries transactionData to sign and execute in order from originAddress on the quoted chain. Batch same-chain legs into one atomic transaction when your wallet stack supports it (see Execute a swap).
3

Poll until settled

Track with GET /v2/swap/status/{quote.quoteId} until fulfilled.
Fees. Read charges from quote.feeBreakdown.charges. Each charge has a kind:
  • paymentRail — the local rail’s pass-through fee (Pix fee, wire fee).
  • bridgeAndSlippage — on-chain execution cost, shown on tokenOut.
  • pods / customer — Deframe or your platform markup, present only on pairs that charge it. BRLA, BRS, BRZ, and the USD rails carry no Pods/customer markup.
Integrate with GET /v2/swap/quote only. New integrations should not call POST /v2/swap/bytecode — the quote response already includes everything you need to pay or sign.

Conventions

  • Amounts are always in the token’s smallest unit. amountIn=1000 with decimals: 2 is BRL 10.00; amountIn=1000000 with USDC decimals: 6 is 1.00 USDC.
  • Chains — originChain / destinationChain accept network names (fiat, base, monad, polygon, ethereum, solana). Responses additionally carry canonical numeric chain ids (chainId, chainIdIn, chainIdOut) when resolvable.
  • Shared query parameters — every pair uses these; per-network sections below only note what changes. The receiving/sending wallet must match an approved Ramp KYC profile for that wallet.

Before you quote: KYC

A user must hold an approved Ramp KYC profile with the relevant currency unlocked before any quote in that currency succeeds.
  • Brazil Pix — full walkthrough in KYC setup guide. In short: submit the Sumsub share token server-side, poll GET /api/v1/kyc/status until approved, then POST /api/v1/kyc/currency-unlock to enable BRL. Share tokens expire quickly and must stay server-side.
  • Foreign USD — requires a foreign profile with usdEnabled: true. Walkthrough in Foreign USD KYC; the currency-unlock errors are catalogued under Errors.

Token addresses

Brazil Pix

Routes by network. Each pair below uses Pix in both directions on GET /v2/swap/quote. The shared Pix payout rules (pixKey validation, BR Codes, third-party payouts) apply to every offramp below.

Pix to Base

USDC on Base (chainId 8453). Fees: a Pix rail fee, optional Pods/customer markup (when configured), and bridge/slippage.

Pix to USDC (onramp)

Pass destinationAddress; the response carries the Pix QR.
Show paymentInstructions.pix.copyPaste to the user. After Pix settles, Pods delivers USDC to destinationAddress.

USDC to Pix (offramp)

Pass originAddress and pixKey; the response carries transactionData.
Execute both legs in order from originAddress on Base (chainId 8453): the first transfers USDC to depositAddress, the next records the transfer for tracking. After Pods confirms the transfer, Pods pays the Pix payout to pixKey.

Pix to Monad

USDC and Morpho hyperUSDCa on Monad (chainId 143). The hyperUSDCa pair deposits into the Morpho vault within the same quote. Fees: a Pix rail fee, optional markup, and bridge/slippage; the yield pair shows fees in feeBreakdown.

Pix to USDC (onramp)

Same shape as Pix → USDC on Base; only the destination network and token change.
Response is the Pix-onramp shape with tokenOut.contract the Monad USDC address, tokenOut.chainId 143, paymentInstructions.pix.copyPaste to pay, empty transactionData, chainId: null. After Pix settles, Pods delivers USDC to destinationAddress.

USDC to Pix (offramp)

Pass originAddress and pixKey; the response carries transactionData.
Same two-leg EVM shape as the Base offramp with chainId 143: transfer USDC to depositAddress, then track. Execute both in order from originAddress on Monad. After Pods confirms the transfer, Pods pays the Pix payout to pixKey.

Pix to hyperUSDCa (deposit into yield)

Deposit Pix BRL into the Morpho Hyperithm USDC Apex vault. Identical to the USDC onramp except tokenOut is the vault share token.
tokenOut.decimals is 18 (vault shares) and expectedAmountOut is a raw share amount of hyperUSDCa, not USDC — store it so you can redeem the exact shares later. feeBreakdown.charges is empty. After Pix settles, Pods converts to USDC on Monad, mints hyperUSDCa, and delivers the shares to destinationAddress.

hyperUSDCa to Pix (redeem yield)

amountIn must be a raw hyperUSDCa share amount — not a USDC amount, and not a principal / currentPosition value from the wallet endpoint (those are in USDC terms). Use the on-chain share balance or the share amount stored from the onramp quote.
Two-leg EVM shape on Monad (chainId 143): the first leg redeems hyperUSDCa to USDC and sends USDC to depositAddress, the next records the transfer. Pods validates the redeem before creating the Pix payout to pixKey.
Reading the position. Use GET /v2/wallets/{wallet} and find the entry whose strategy matches Morpho Hyperithm on Monad. spotPosition.currentPosition, principal, profit, and cumulativeProfit are reported in USDC terms even though the wallet holds hyperUSDCa shares on-chain — do not use them as amountIn here. To exit into USDC on Monad without Pix, use that strategy’s withdraw bytecode endpoint (underlying-token amount); see Withdraw from a yield strategy.

Pix to Polygon

BRLA and BRZ on Polygon (chainId 137). Neither carries Pods/customer markup; an optional Pix fee may appear as paymentRail.

Pix to BRLA (onramp)

BRLA is minted directly to destinationAddress — no Deframe inventory hop.
Pix-onramp shape with tokenOut BRLA (decimals 18, chainId 137), feeBreakdown without Pods/customer charges, empty transactionData, chainId: null. After Pix settles, Pods delivers BRLA to destinationAddress.
Use this pair to deliver BRLA; use Pix → USDC to deliver USDC. Do not integrate the underlying rail provider directly — use GET /v2/swap/quote.

BRLA to Pix (offramp)

Pass originAddress and pixKey; the response carries transactionData.
amountIn is in 18 decimals. BRLA uses no EIP-2612 permit: transactionData has two legs on Polygon (chainId 137) — an ERC-20 transfer of BRLA to the deposit address for this quote, then a Deframe Track event (version 0, action 2, quote.quoteId). The destination is the to of the transfer leg; there is no top-level depositAddress. A transfer without the matching Track does not confirm the quote. After Pods confirms the transfer, Pods pays the Pix payout to pixKey.

Pix to BRZ (onramp)

Pricing is 1:1 (BRLA 18 ↔ BRZ 18). The user never holds BRLA — Pods settles that inventory internally. The Ramp KYC walletAddress and destinationAddress must be the user’s Polygon address.
Pix-onramp shape with tokenOut BRZ (decimals 18, chainId 137). After Pix settles, Pods delivers BRZ to destinationAddress.

BRZ to Pix (offramp)

Pass originAddress and pixKey; the response carries transactionData.
amountIn is in 18 decimals. BRZ also has no EIP-2612 permit: transactionData is an ERC-20 transfer of BRZ to the Pods bridge address plus a Deframe Track event (version 0, action 2, quote.quoteId). A transfer to the bridge without that matching Track does not confirm the quote. After Pods confirms the transfer, Pods pays the Pix payout to pixKey.

Pix to Solana

BRS (Nora) on Solana (chainId 0). No Pods/customer markup; 1:1 BRLA inventory after decimal scale (BRLA 18 ↔ BRS 6); an optional Pix fee may appear as paymentRail.

Pix to BRS (onramp)

The user never holds BRLA; Pods settles that inventory internally. The Ramp KYC walletAddress and destinationAddress must be the user’s Solana public key.
Pix-onramp shape with tokenOut BRS (decimals 6, chainId 0), paymentInstructions.pix.copyPaste to pay, empty transactionData, chainId: null. After Pix settles, Pods delivers BRS to destinationAddress.

BRS to Pix (offramp)

Pass originAddress and pixKey. The origin payload is Solana, not an EVM array.
amountIn is in 6 decimals. Default output=bytecode returns type: intra-chain-solana with transactionData.rawTransaction (base64). That transaction transfers BRS to the Pods inventory ATA and includes Memo V1 { version: 1, actionId }, where actionId is the quote UUID (quote.quoteId), not the Action ObjectId. Sign and submit it from originAddress. Wallets that assemble instructions themselves can request output=instructions (Solana-origin only; bytecode is the default). EVM and fiat origins reject instructions with OUTPUT_NOT_SUPPORTED. After Pods confirms the transfer, Pods pays the Pix payout to pixKey.

Pix to Stable

USDT0 on Stable (chainId 988). USDT0 is Stable’s gas token; Pods quotes and pays it as the ERC-20 at 0x779Ded0c9e1022225f8E0630b35a9b54bE713736 (decimals 6). Pricing follows the USDC Pix rail (USDT0 at USD parity). Fees: a Pix rail fee, optional Pods/customer markup (when configured), and bridge/slippage.

Pix to USDT0 (onramp)

Same shape as Pix → USDC on Base; only the destination network and token change.
Pix-onramp shape with tokenOut USDT0 (decimals 6, chainId 988), paymentInstructions.pix.copyPaste to pay, empty transactionData, chainId: null. After Pix settles, Pods delivers USDT0 to destinationAddress.

USDT0 to Pix (offramp)

Pass originAddress and pixKey; the response carries transactionData and a depositAddress unique to this quote.
amountIn is in 6 decimals. Pay the quote in one of two ways:
  • Bytecode. Execute every transactionData leg in one batch from originAddress on Stable (chainId 988): an ERC-20 transfer of USDT0 (net of customer markup) to the Pods bridge address, a second USDT0 transfer of the customer markup to your fee collector when markup is configured, then a Deframe Track event for quote.quoteId. Pods confirms the quote only when that Track group pays the exact amounts. A transfer without the matching Track, or a reverted transaction, does not confirm it.
  • Plain deposit. Send exactly quote.tokenIn.amount of USDT0 to depositAddress. Native USDT0 sends and exchange withdrawals work: Stable records them as the same ERC-20 transfer. A deposit that does not match the quote, or that arrives after the quote expires, is repriced as on the other USDC Pix offramps.
Use only one path per quote. Pix pays out once, and Pods does not automatically refund a second payment or an overpayment.
After Pods confirms the transfer, Pods pays the Pix payout to pixKey.

Pix payout rules

These apply to every Pix offramp above.
  • pixKey validation. An explicitly supplied pixKey is trimmed and validated. Invalid or unknown keys return 400 INVALID_PIX_KEY; empty keys are rejected (missing required destination inputs may surface 422 VALIDATION_ERROR first). A successful lookup confirms the key resolves to a recipient — it does not confirm it is the recipient the user intended. Recipient-lookup details are not added to the swap response. Keys supplied only through destinationAddress or saved quote data do not trigger this check.
  • Pricing-only fallback. When the ordinary-key lookup is unavailable, a quote with an origin wallet and a destination can still generate funding instructions: an explicit upstream HTTP 5xx lets the request continue, while timeouts, auth/rate-limit errors, and incomplete responses return 502 PIX_KEY_LOOKUP_FAILED. This fallback does not bypass KYC, ownership, third-party, or payout checks.
  • BR Codes must be supplied as pixKey when requesting the quote. All Pix offramps validate their format, checksum, metadata, and expiration before pricing; the outage fallback above does not apply. A fixed-amount code determines amountOut, and the quote calculates the required crypto input including fees. Keep the same code when requesting payment bytecode. Adding or changing a BR Code, or replacing a quoted code with an ordinary key, returns 400 PIX_BRCODE_REQUOTE_REQUIRED; request a new quote first. Codes that expire before acceptance return 400 PIX_BRCODE_EXPIRED.
  • Third-party payout. By default the pixKey must belong to the same person as originAddress. To pay someone else, set thirdParty=true and pass the recipient’s pixKey (USDC on base or monad). Everything else matches a normal offramp; only the payout recipient differs.

Wire to USDC

Move money between a USD bank wire and USDC. There is no Pods/customer markup on this rail — the only fee is the WIRE rail fee, shown as a paymentRail charge. Requires a foreign KYC profile with usdEnabled: true — see Foreign USD KYC.
With rampProvider=unblockpay, the paymentRail charge is UnblockPay’s flat wire fee (plus any partner fees), in USD in both directions. UnblockPay also prices a small FX spread into its rate. That spread is not itemized: on the onramp it shows as bridgeAndSlippage, and on the offramp it is already in tokenOut.amount.
USDC settles on Base (8453) or Polygon (137); pick it with destinationChain (onramp) or originChain (offramp). Each direction accepts exactly one of amountIn or amountOut:
  • Onramp — amountIn is USD cents to send; amountOut is USDC raw to receive.
  • Offramp — amountIn is USDC raw to send; amountOut is USD cents to receive.
The WIRE fee is ~10 USD, so prefer amountOut when the product promise is “receive exactly N”.

Wire to USDC (onramp)

Onramp: the user pays USD by bank wire and receives USDC. Pass destinationAddress; the response carries the bank wire instructions.
Example: receive exactly 4 USDC → send ~USD 14.04 (WIRE In Fee ~USD 10).
Show paymentInstructions.usd to the user: After the wire settles, Pods delivers USDC to destinationAddress. Poll GET /v2/swap/status/{quote.quoteId} until fulfilled.

USDC to Wire (offramp)

Send USDC, receive a USD bank wire. Pass originAddress plus the beneficiary bank fields — Pods resolve-or-creates the payout beneficiary (matching account + routing reuses the existing record; otherwise it registers one). With those fields present, the response includes transactionData to sign — there is no paymentInstructions block, since the user pays on-chain.
The WIRE Out Fee (~10.04 USDC) already sits in the spread between tokenIn.amount and tokenOut.amount, and also appears as a paymentRail charge on tokenIn. With amountIn, USD out is net of that fee. With amountOut, tokenIn.amount is the USDC the wallet must transfer (fee included). A 5-USDC amountIn does not cover the WIRE fee, so use amountOut or an amountIn above ~10 USDC. Example: receive exactly USD 4.00 → send 14.035088 USDC (WIRE Out Fee ~10.035 USDC).
Execute both legs in order from originAddress, signing with each item’s chainId (base → 8453, polygon → 137). The first transfers USDC to depositAddress; the next records the transfer. After Pods detects the USDC, Pods pays the wire to the resolved bank account.

Errors

Reference