Skip to main content
This API allows you to integrate on/off ramps and swaps into your application. Your customers can buy tokens with fiat (onramp), sell tokens for fiat (offramp), or exchange one token for another (swap).
Use the sandbox for development. All examples in the guides work with the sandbox environment at https://api.sand.etherfuse.com. If you haven’t set up your sandbox account, see Initial Setup.

​
Integration Flow

The typical integration follows this pattern:
1

Onboard Customer

Generate a presigned URL and have your customer complete KYC verification, bank account linking, and agreement signing. You generate the customerId and bankAccountId UUIDs — store them, as they’re permanently bound after onboarding.Two approaches: Hosted UI (fastest) or Programmatic (white-label). See Onboarding Customers for details.
2

Get Available Assets

Discover which assets your customer can buy, sell, or swap. Use GET /ramp/assets (auth required, returns all rampable stablecoins and stablebonds for the chain, sorted by currency priority) or GET /lookup/stablebonds (public, all assets). Use the identifier field from the response when creating quotes.
3

Create Quote

Get pricing via POST /ramp/quote. Quotes expire after 2 minutes. Key response fields:
FieldMeaning
exchangeRateThe customer-facing rate, after fees.
nominalRateThe pre-fee underlying rate (FX rate, or the bond/wrap rate).
etherfuseMidMarketRateFX mid-market reference rate — present only for cross-currency (FX) quotes; absent on direct stablebond ramps.
feeBps / feeAmountThe fee in basis points and absolute amount (includes any Stellar wallet-setup cost).
destinationAmountWhat the customer receives.
requiresSwaptrue when the quote needs an on-chain swap.
expiresAtHard expiry — create the order before this.
See the detailed guides for quote examples: Onramps, Offramps, Swaps.
4

Create Order or Swap

Execute using the quote. For on/off-ramps, call POST /ramp/order — the order inherits direction and amounts from the quote. For swaps, call POST /ramp/swap.See Testing Onramps, Testing Offramps, or Testing Swaps for the full flow.Need to back out an order that hasn’t been funded yet? Cancel one still in created status with POST /ramp/order/{order_id}/cancel.
5

Monitor via Webhooks

Subscribe to webhooks via POST /ramp/webhook to receive real-time updates. See Webhooks for event types, status flows, and scenarios.

​
Quote Types

TypeSourceTargetUse Case
onrampFiatTokens (USDC, CETES, etc.)Customer buys tokens
offrampTokens (USDC, CETES, etc.)FiatCustomer sells tokens
swapTokenTokenCustomer exchanges one token for another

​
Supported markets, chains & assets

Coverage
Live marketMexico — fiat MXN over SPEI.
Upcoming marketsBrazil (BRL), Korea (KRW), Argentina (ARS). See Fees.
On/off-ramp chainsSolana, Stellar, Base, Polygon, Monad.
Swap chainsStellar and Solana only (not yet on EVM).
AssetsYield-bearing stablebonds (e.g. CETES) and stablecoins (e.g. USDC), per chain.
Each chain has its own asset-identifier format and setup (trustlines, gas, approvals). See the per-chain guides — Solana, Stellar, Base, Polygon, Monad.
Always discover assets with GET /ramp/assets (or the public GET /lookup/stablebonds) rather than hardcoding identifiers. Identifiers — especially Stellar issuers — differ between sandbox and production and can change.

​
Fees

Platform fees are volume-based (lower fees at higher volume), plus an optional partner fee you can layer on top. Mexico (MXN) is live; Brazil, Korea, and Argentina are upcoming. See Fees for the full breakdown.

​
Webhooks

Etherfuse pushes signed, real-time events for orders, swaps, KYC, and bank accounts. See Webhooks for how delivery works, the full event catalog, the order/swap status flows, common scenarios, and best practices — and Verifying Webhooks for signature-verification code.

​
Resources

The API manages these resources, all scoped to your organization:
  • Organizations (organizationId) — Your organization and any child organizations you create. Child orgs can be created programmatically via POST /ramp/organization and renamed via PUT /ramp/organization/{org_id}/name.
  • Customers (customerId) — Your end users who complete KYC. You generate this UUID during onboarding.
  • Bank Accounts (bankAccountId) — Mexican bank accounts linked to a customer. You generate this UUID during onboarding.
  • Wallets (publicKey) — Wallet addresses registered during onboarding. Can also be registered programmatically via POST /ramp/wallet or scoped to a child org customer via POST /ramp/customer/{customer_id}/wallet.
  • Orders (orderId) — Onramp and offramp transactions. You generate this UUID.
  • Webhooks — Event notification subscriptions.

​
Troubleshooting

See the Errors reference for every status code and common error message (Proxy account not found, Bank account not found, Quote expired, …), and Authentication for 401 issues.

​
Common Pitfalls

  • IDs are permanently bound after onboarding. The customerId, bankAccountId, and publicKey are linked during onboarding. You cannot mix and match IDs across different customers.
  • Stellar: trust lines are handled automatically for onramps. Pass walletAddress in your quote request to enable automatic wallet setup. If the wallet lacks a trustline or doesn’t exist on-chain yet, the quote fee will include a one-time onboarding cost. After the order completes, the order response includes a stellarClaimTransaction — an unsigned XDR that the user signs to add the trustline and claim their tokens. See Stellar: First-Time Wallet Onramp for the full flow. For offramps and swaps, the wallet must still have trust lines set up beforehand.