Copy page

Products

Buy & sell

available

Quote and route a crypto purchase or sale across every connected provider — one best executable route, with the fee breakdown shown up front, not discovered at checkout.

Concept

A quote prices a side (buy or sell), an asset pair and an amount across every connected provider and returns the best executable route. An order is what you get when a quote is turned into an actual attempt to transact with that provider.

Which sides are open. Buying and selling are live. Swapping is paused: POST /v1/quotes with side: swap answers 409 capability_unavailable with param: side and error.details.reason_code: TRADE_PAUSED before any pricing, and POST /v1/orders refuses a stored swap quote the same way. Do not offer a swap.

Selling. A sale is a stablecoin sold through Bridge — only Bridge executes a sell — and paid out to a bank account in the seller's own name by ACH, wire, SEPA, Faster Payments, PIX or SPEI. The stablecoin and the network it is sent on must be a launchable pair: USDC on arbitrum, avalanche, base, celo, ethereum, optimism, polygon, solana, stellar and tempo; USDT on ethereum, solana and tron; USDB on base. Residents of the EEA sell USDC only: for a country in the EEA, USDT and USDB are not priced. On a Bridge sell, total_fees.swaps is Swaps' 1 % fee, and on a sale that converts currency Bridge's FX spread is part of total_fees.provider. The order answers with a deposit instruction — see Minimal flow.

Resources

Object	What it is
quotes	rate, final_out, final_in, total_fees, expires_at, plus the winning offer_id, every priced offers[] route, and terminal per-provider outcomes (quoted, no_offer, paused, error) from the same quote call.
orders	The attempt itself — status is the public lifecycle; money_state (never_authorized / hold_placed / captured) is the actual money truth, never inferred from status alone. Published only once a row has been classified — absent otherwise, and absence is never never_authorized or any other value.

Lifecycle

Quotes are ready or indicative and always carry an expires_at — re-quote rather than reuse a stale one. An order's public status is the one lifecycle field on the wire (draft/quote_ready/etc. is not a separate enum — the hand-off to a provider's own checkout is read from whether next_action is present, with its type, checkout_url and expires_at); money_state, when classified, is reconciled with it on the same object, never a second, disagreeing status field.

total_fees itemizes what the payer pays on the route, and every leg is already inside final_out. provider is the provider's fee — on Bridge, Bridge's part: its 0.10 % USDT conversion fee on a USDT route and, on a cross-currency route (EUR, GBP, MXN, BRL, COP), its FX spread as an amount, rounded up to the cent (already inside rate and final_out, so named here, not deducted twice); 0 on a same-currency route with neither; network is 0 on every Bridge rail (a fee the payer's own bank charges to send a wire is outside the quote); on a Bridge wire buy provider includes Bridge's own $10 wire fee, passed through at cost and listed in /v1/capabilities?product=buy_sell provider_fees (a sell's outgoing wire carries none), and Bridge wire buys start at $100; a Bridge cross-currency buy is priced at Bridge's mid-market rate less its FX spread (EUR, GBP, MXN 0.50 %; BRL 0.55 %; COP 0.75 %), inside rate and final_out; swaps is Swaps' own fee where Swaps charges it directly — the Bridge developer fee (1 % today, also on Bridge's receipt) — and 0 on a route with no Swaps share (Stripe Onramp). On routes where Swaps' share is a markup inside the provider's price (Transak, Onmeta), it is not itemized and stays inside provider; the amount received is always net. Never present an absent swaps as no Swaps fee; the per-route shares are on the public pricing page.

checkout_readiness carries provider-specific handoff and freshness facts. ready means the quote passed those checks; it does not guarantee the final provider price, verification eligibility or settlement. An indicative quote retains its actual indicative_as_of; re-quote live before acting.

providers contains one row per provider observed in the existing call, ordered by provider ID. A usable offer wins over a failure on another payment method for the same provider. Each quoted row includes its selectable offer.offer_id. A route with no usable offer returns 409 capability_unavailable, with safe terminal outcomes in error.details.providers when available. Raw diagnostics and provider payloads are private.

offers[] contains every fully priced route from that fan-out, including sibling payment methods. Each entry binds the canonical payment_method when known and opaque offer_id to its provider, readiness, expiry, resolved limits and non-PII execution_context (assets, amount side, and supplied route selectors). Use entries with a known method when presenting or selecting a method; unknown methods remain visible but are never inferred. Capabilities are not substituted for missing quotes.

rate — on the winner, every offers[] entry and every providers[].offer echo — is each offer's own final_in decimal value ÷ final_out decimal value, computed BEFORE either is rounded into the published Money fields, one basis (from_asset per to_asset) computed the same way for every offer regardless of provider or side. Because the derivation runs pre-rounding, rate × the published final_out amount can differ from the published final_in amount in the last digit(s) when an asset's published decimals are coarser than the server's own internal precision — treat that cross-check as approximate, not exact. It is informational only: never rank or compare offers by rate. For a from_amount request, compare by final_out instead — every offer targets a different final_out for the same pay amount, so the largest wins. For a to_amount request, compare by final_in only among offers whose final_out equals the requested amount — the lowest pay amount among those wins. An offer whose final_out differs from the requested amount is not comparable this way: not every provider honors an exact-output target.

The winner and each provider offer may include payment_method, the canonical method priced for that specific offer_id. Preserve both when presenting or selecting an offer. A different offer from the same provider can use another method; missing payment_method means unknown, so do not copy it from the request or winning offer. The field describes the priced payment intent and does not establish customer eligibility or guarantee the eventual settlement rail.

For Transak offers on a coin that exists on several networks (USDT, USDC, ETH), specify the crypto network (to_network when buying, from_network when selling). An unspecified network cannot authorize its checkout. Other usable provider offers remain available; when none remain, 409 capability_unavailable includes QUOTE_NETWORK_REQUIRED and the network field to provide. A buy of a coin on one network only (BTC, XRP, SOL, BNB) needs none: Transak prices it and checks it out on that network. A network you name always wins.

POST /v1/quotes needs a credential. An anonymous caller gets an indicative estimate from GET /v1/quote_estimates instead (see Before sign-in below) — never a quote, never accepted by POST /v1/orders; the legacy public widget transport is unchanged. Test-mode /v1/quotes requests currently return 503 temporarily_unavailable before any provider request; sandbox dispatch remains pending.

When sent, country must be an uppercase ISO 3166-1 alpha-2 code; a comprehensively-sanctioned or unsupported one is refused with 409 capability_unavailable before pricing runs, even when country is omitted and only inferred from a forwarded geo header.

GET /v1/capabilities?product=buy_sell provides authenticated provider status and coverage filtered by country, method and provider; GET /v1/capabilities/buy_sell serves the same projection without a credential (see Before sign-in). The authenticated projection covers buying only; the anonymous one also answers side=sell. Neither establishes the caller's provider KYC eligibility. A degraded snapshot is a failed availability check, not proof that no route exists. defaults.fiat_reason says why default_fiat is the currency shown: local_currency (the country's own), fallback_fiat (the country's own currency has no buy route in the snapshot, so this is the first fallback that has one — name it as not the local currency) or requested. It is optional; treat its absence as not stated.

Before sign-in

These operations answer the buy and sell widget before the person signs in. They take no key and no session (security: []), and each is dark-flag: switched off in production until launch, it answers 503 temporarily_unavailable with Retry-After. Do not build on them until they open. What follows is the contract they carry when they do.

Operation	What it answers
GET /v1/quote_estimates	An indicative buy or sell price (QuoteEstimate) from the quote cache: per provider and method, what is paid and received, the fee lines, the delivery time when the provider gave one, and whether the route needs an ID document (identity). side=buy or side=sell; swap answers 409 capability_unavailable.
GET /v1/capabilities/buy_sell	The same buy coverage GET /v1/capabilities?product=buy_sell returns for the same country, method and provider; with side=sell, the sell coverage (sell_defaults, sell_coverage).
GET /v1/capabilities/buy_sell/countries	Every supported country in brief (BuySellCountrySummaryList): its paying currencies and, per currency, how many payment methods are selectable for buying — the same count the per-country coverage gives, from the same stored snapshot; with side=sell, the payout currencies and payout methods. For labelling a country list; read GET /v1/capabilities/buy_sell for the country the person picks.
POST /v1/address_checks	Advice on one destination address (network and address in the body): allow, offer_report, block or not_screenable, with the time the screening data was produced.

An estimate is not a quote. It has no id and no offer_id, nothing in it can be selected, and POST /v1/orders requires a quote_id from POST /v1/quotes, so an estimate can never become an order. Every estimate is quote_status: indicative, dated by indicative_as_of (when the providers priced it) and expires_at (after which it is too old to show; it is not a provider deadline). Each offer's identity comes from the same identity policy the authenticated quote path applies — by provider, the method actually quoted, the fiat currency and the requested amount. Any uncertainty reads required: true; no-ID is only the documented exception (OnMeta in IDR via QRIS and in PHP via QR Ph, with a warning that OnMeta may still ask above its own limit). It describes the provider's policy for the route, not the person. An estimate carries no limits: read each method's limits from the coverage operation (defaults.resolved_limits), and take the binding quote at review. providers lists only the providers that priced the route, plus Paybis as paused — it is no availability claim for any other provider. country is required; a sanctioned or unsupported one is 409 capability_unavailable (COUNTRY_NOT_SUPPORTED). Paybis is never offered here either. When the providers need a network, the answer is 409 capability_unavailable with QUOTE_NETWORK_REQUIRED — set to_network; a coin on one network only (BTC, XRP, SOL) is estimated on it without one.

Selling before sign-in. GET /v1/quote_estimates?side=sell takes the stablecoin sent (from_asset), the network it is sent on (from_network, required), the fiat paid out (to_asset) and either from_amount (what is sent) or to_amount (what is paid out); to_network is refused. Only a launched sell pair is estimated — any other is 409 capability_unavailable with param: from_network before pricing, and a payout currency the pair cannot be paid out in (Bre-B/COP included) is 409 with param: to_asset — and only Bridge sells today: another provider's sell price is listed paused, never offered. On a sell, from_amount is in the asset, while to_amount and every fee line are in the payout fiat, as in the binding sell quote; identity.required is always true. GET /v1/capabilities/buy_sell?side=sell answers side: sell, sell_defaults and sell_coverage instead of defaults and coverage. Each sell_coverage cell is one payout method and fiat the country can be paid in, Bridge as provider, and lists the assets that may be sent on it — asset, network, state and, when selectable, min and max in that asset, min being the minimum the sell quote enforces. Bre-B (COP) is blocked with route_disabled: Bridge prices it, but a sell order cannot pay out on it. USDT and USDB are blocked with policy_blocked for a country in the EEA. sell_defaults starts on the country's own currency (else its fallback, else USD, EUR or GBP, named by fiat_reason), USDC on Base, and the first selectable payout method with its USDC resolved_limits. A sell answer carries no provider_fees: there is no pass-through provider fee on a sell.

A country summary row is status: ok only when it was built from a fresh snapshot, and only then carries currencies, ways, default_fiat and, when stated, fiat_reason; an ok row with no currencies has no way to pay today. Any other row is unknown and claims nothing — never read it as not available. degraded: true means at least one row is unknown; as_of is when the route truth behind the oldest snapshot used was read. The answer is the same for every caller; it is Cache-Control: private for at most 60 seconds and never past the earliest snapshot's expiry, like the per-country read, so every answer carries its own x-request-id.

An address check publishes no score, level or label and stores nothing. not_screenable means screening does not cover that network or address format — nothing was checked, so it is neither clean nor risky. A check that cannot complete is 503, never allow. It is advice only: POST /v1/orders screens the destination again and refuses a blocked one (destination_blocked), so never present an address check as that screening.

Each operation has a per-client-IP limit (the country summary shares the coverage read's limit and switch): an exceeded one is 429 rate_limit_error, a limiter that cannot be consulted is 503. A client IP on the Swaps block list is refused 403 with code ip_not_allowed. None of them is an MCP tool: quotes are never quietly added to the public agent surface (API-CANON §13). An agent prices with get_quote, reads coverage with list_capabilities and screens with check_address_risk, each under a business key.

Minimal flow

1. Authenticate with a business key or bearer holding orders.write, then call POST /v1/quotes — or the MCP tool get_quote — with side, assets, amount, the crypto network (to_network for buy, from_network for sell), in the US the state as region (the one the estimate used — Stripe Onramp prices a US route only with it), (when known) country and payment method, and hosted_handoff: true if you will create the order here and follow its next_action (it adds COP PSE through Bridge, paid on Bridge's own page).

2. Present the route and its fees to the person; quotes expire, so don't hold one past its expires_at. A quote or selectable offer_id alone never authorizes execution — the person must see the route and its fees first (see What an agent can and cannot do here below).

3. Create the order: POST /v1/orders with quote_id and the chosen offer_id. Execution depends on the selected provider and side; a quote alone does not establish eligibility. A test-mode (sk_test_) key cannot create an order — orders.create answers 503 temporarily_unavailable ("Test-mode orders are not available yet") before any other check (see Test mode). This is a live money boundary, but a created order is not evidence of payment or settlement. Tell the execution path apart before calling create by the offer's own checkout_readiness.handoff_mode: backend_native is a Bridge-native order; any other value is a hosted provider.

   • Bridge-native buy: send wallet_address — required for a Bridge-native buy; the quote must contain to_network. A quote priced without it answers 409 capability_unavailable (param: quote_id), "This quote has no to_network — request a new quote with to_network set before creating a Bridge-native order". Re-quote with to_network set and retry. The order is created in place without a hosted checkout page (except a COP PSE buy, below). A buy on pix, spei, bre_b, faster_payments or sepa also needs the customer's Bridge approval for that rail (pix_onramp, spei, cop, faster_payments, sepa in endorsement_statuses[]), read live before anything is reserved or sent: without it the order is refused 403 endorsement_required with details.payment_rail, details.endorsement and details.next — verify (mint a kind: kyc verification link with that rail, Customers), accept_terms (a kind: tos link first), complete_profile (Bridge needs a questionnaire the hosted flow does not collect), provider_review (Bridge is holding it — nothing to do) or not_available (Bridge does not offer the rail to this customer). Once the step is done, quote again. USD rails are not pre-checked; when Bridge itself refuses the rail at transfer time the same code answers, with details.order_id when an order row was already written. COP bank transfer — PSE (co_bank_transfer) through Bridge is offered on /v1 to a caller that sends hosted_handoff: true on its quote (and hosted_handoff=true on its estimates) — that is, one that orders here and follows next_action; without it no PSE offer is priced, and Swaps' legacy web and iOS checkouts don't offer it until they support the hand-off. It needs the same cop approval as Bre-B. Bridge collects it on its own hosted page, so send return_url (required for this rail — without it the order is refused 400 invalid_request, param: return_url, before anything is sent): the order carries no bank_deposit_instructions but a next_action (type: redirect) — open checkout_url, Bridge's page, for the payer before expires_at; Bridge returns them to return_url. GET /v1/orders/{id} keeps that next_action while the order waits for payment. Its host is whatever Bridge serves the page from (published when it is https with no user name or password); a page that fails that answers 502 provider_handoff_invalid with details.order_id — the order exists but cannot be paid here, so reconcile it rather than retry. A Bre-B (bre_b) buy's bank_deposit_instructions carry the bre_b_key to pay to.
   • Bridge-native sell: send an owned external_account_id matching the payout currency and rail; the quote must contain from_network, and the asset and network must be a pair a sell can be made on — USDC on arbitrum, avalanche, base, celo, ethereum, optimism, polygon, solana, stellar and tempo; USDT on ethereum, solana and tron; USDB on base (anything else is 409 capability_unavailable). Only a Bridge offer (checkout_readiness.handoff_mode: backend_native) becomes a sell order; another provider's sell offer answers 409 capability_unavailable. Do not send wallet_address — it is refused. The response carries deposit_instructions: send exactly amount of asset on chain to address, in one transfer, with memo when it is present (Stellar, Tron); amount is the amount the order was quoted for. The order sells the first deposit that arrives, whatever its amount, and a later deposit is not added to it (the order's amounts.pay becomes the amount received), while a deposit below the sell's minimum may not complete the sale. The payout follows what arrives: Bridge takes the 1 % fee from it, rounded up to the cent, and, on a currency conversion, converts at its own rate at that moment, so the payout can differ from the quote. A deposit on another network or without its memo does not complete the sale, and crypto sent to a wrong address or on a wrong network may be lost. A sell waits for its deposit until deposit_instructions.expires_at (24 hours after the order was created), then it is cancelled; that is the sell's only deadline — the order itself has no expires_at. Bridge gives the customer one deposit address per network and reuses it, so one transfer at a time waits there: a second open sell on the same network and asset, whatever its amount, answers 409 order_already_open with the open order in details.order_id — send to that order or cancel it first. While that address is held by something that is not an open sell order, the sell answers 409 deposit_in_use, never with details.order_id: a Pay an invoice payout being funded on that network (details.payout_id when it can be read — fund or cancel that payout first), an earlier sell on that network that Bridge has not yet confirmed (try again later; a retry of the same quote, offer and account is not refused by it), or a Swaps Wallet withdrawal of USDC on Tempo waiting for its deposit. The other way round, funding a payout (POST /v1/payouts/{id}/fund) and withdrawing from a Swaps Wallet to a bank (POST /v1/wallet/offramp_intents) are refused while a sell holds the address. The per-order and daily limits are checked on the quoted amount; a larger deposit is still sold, and the amount received counts toward the daily limit for 24 hours from when it arrived. Save the account first with POST /v1/wallet/external_accounts — ach/wire (USD), sepa (EUR, its IBAN and its BIC, both required), spei (MXN), faster_payments (GBP) and pix (BRL), see Wallet — and, before you offer a rail, check the customer's endorsement_statuses[] for it; a kind: kyc verification link with that rail asks the provider for the approval (Customers). While the sale runs, progress.stage on the order says where it stands inside status: awaiting_deposit (Bridge is waiting for the crypto), received (Bridge has it), paying_out (the bank payout is sent) or paid (Bridge reports the payout processed). It is absent for any other order, for a review, return or failure, and when it would disagree with status — never infer a stage, or that money moved, from its absence. Supported execution rails are documented in the reference.
   • Hosted buy (Transak, OnMeta, Stripe Onramp, Partna): send wallet_address (or address_book_id, below); the account must have a verified email on file. A successful create returns status: awaiting_payment and next_action {type: redirect, checkout_url, expires_at}. Open the URL for the payer before it expires. Partna buys are Nigerian naira by bank transfer, and they execute only while feature_flags.partna_quote_breakdown is on. It ships off, so until it is turned on a Partna offer answers 409 provider_not_supported, "This provider is not available through this endpoint yet" (the only offer that code answers); while it is off, a Partna offer on a quote is priced by Partna's rate less the fees Partna states (total_fees.provider and network, in naira). Either way, a quote that gives to_amount has no Partna offer: Partna is priced only for an amount to pay. A hosted sell answers 409 capability_unavailable, "A hosted-provider sell is not available through this endpoint yet". An offer from a hosted provider this endpoint does not run answers 409 capability_unavailable, "This offer is not executable through this endpoint" (with error.details.eligible_offer_ids when you pinned it). Never retry any of them as-is.
   • OnMeta, Stripe Onramp and Partna amounts (for Partna, only while its buys execute, as above): the checkout is opened for the offer you were quoted — its final_in is what the payer is charged and its final_out what they receive, on the offer's execution_context.to_network — never for an amount on the request. An offer priced without to_network answers 409 capability_unavailable. OnMeta and Partna price again when their checkout is opened, and so does a Stripe Onramp checkout opened after its fresh window. If that price moved by 0.5% (50 bps) or more, the create answers 409 conflict, code requote_required, with error.details.reason: price_moved, drift_bps and quote_id, and no checkout URL: request a new quote. This refusal is not side-effect-free: the order it started is closed at once as abandoned — money_state: never_authorized, money_status: not_charged, because no checkout ever reached the payer — and is named in error.details.order_id. Do not retry the same quote. If OnMeta or Partna cannot prepare the checkout at all, the create answers 503 temporarily_unavailable naming the quote and the same kind of abandoned order: request a new quote. Stripe Onramp has a 30-second quote lifetime, so create its order promptly after quoting. OnMeta orders are capped per account over a rolling 24 hours at INR 1,500,000, IDR 45,000,000 and PHP 150,000, and Partna orders at NGN 15,000,000; past that, the create answers 422 amount_invalid. An order closed as abandoned with money_state: never_authorized does not count toward that cap.
   • Paybis: refused with 409 capability_unavailable / provider_paused on /v1, and excluded from its quotes. This restriction does not describe the separate public widget transport.
   • A provider switched off: an offer runs only while Swaps has its provider switched on. A provider switched off — or never given a switch — answers 409 capability_unavailable / provider_paused with error.details.eligible_offer_ids when you pinned its offer_id, and is skipped when you did not. Choose another offer or re-quote.

   Returning the payer (return_url, optional): where Transak and OnMeta send the payer after checkout. It must be https, on https://swaps.app, https://www.swaps.app or https://staging.swaps.app, at most 2048 characters, with no query string, fragment or credentials — carry an order reference in the path, never personal data. Anything else is 400 invalid_request with param: return_url; it is never swapped for a default. Without it, the payer returns to the Swaps /success page. Stripe Onramp's and Partna's hosted checkouts do not send the payer back, and a Bridge-native order has no hosted checkout, so for those the field is checked and not used: follow such an order with GET /v1/orders/{id}.

   Paying out to a saved address (address_book_id, optional, dashboard session only): for a buy, send the adr_… id of a crypto entry from GET /v1/address_book instead of wallet_address. The address and network come from the entry. If you also send wallet_address, it must match the entry byte for byte — addresses are case-sensitive — or the create answers 400 with param: wallet_address. The entry must be saved for the quote's to_network; a network name is matched the way screenings match it, so Ethereum, eth and 1 are one network and base is another. Otherwise the create answers 400 with param: address_book_id, as it does for a bank entry or a sell. An entry whose latest screening blocked it answers 403 destination_blocked. An id that is not yours answers 404. A business key cannot use the address book and gets 403 scope_denied. After a 201, the entry's last_used_at is set, so GET /v1/address_book can list recently used addresses first. The destination is still screened at order time, exactly like a typed address.

   For hosted checkout, replaying the same idempotency key returns the stored response, whose handoff may have expired. Re-read the order to obtain its current next_action. A sequential create under a new key for the same quote and offer reuses the active order, or returns checkout_expired when its handoff is no longer open. Concurrent requests with different keys are not serialized by that reuse check. After an ambiguous failure without sideEffectFree, reconcile before retrying; never assume a new key is harmless.

   The wallet_address itself can also be refused by destination screening: 403 permission_error (code destination_blocked) on a flagged address — never retry as-is — or 503 temporarily_unavailable (code destination_check_unavailable) when screening is itself unavailable and the fail-closed policy blocks the create — retry after the response's Retry-After. A Swaps Wallet address is accepted only on Tempo and only with a key Swaps can confirm, before any order row or provider call: 422 destination_rail_keyless on another network (or a hosted offer with no network bound), and 422 destination_wallet_disabled, destination_wallet_key_reported_lost, destination_wallet_signer_at_risk or destination_wallet_signer_unconfirmed for a wallet that cannot take new money — choose another destination, do not retry; 503 destination_risk_unverifiable when the check could not run.

   Two more answers are conflicts, not bugs, and worth telling apart from an actual defect: a stale offer — past its own expires_at or checkout_readiness.checkout_fresh_until — answers 409 conflict (code requote_required); request a fresh quote and create the order from the new offer_id. A create that reconciled onto an already-existing order — made by a prior attempt under a different Idempotency-Key, recovered through Bridge's own provider-side idempotency key, rather than creating a second one — still answers 201, but carries Idempotent-Replayed: true; read that header before booking this call as having made a new order. See Errors for the full code reference.

4. GET /v1/orders/{id} — read money_state, when present, before ever telling a user money moved.

What an agent can and cannot do here

get_quote prices a route; nothing about pricing a quote authorizes spending. An order is created from a quote, never chained straight from a quote response without the person seeing the route and its fees first — the same human-in-the-loop rule every money-preparation tool follows (see Agents & MCP).

Next: the reference for the full quote and order schemas · Providers & coverage for which providers and countries are actually live.