> ## Documentation Index
> Fetch the complete documentation index at: https://docs.etherfuse.com/llms.txt
> Use this file to discover all available pages before exploring further.
# How it works
> How an Etherfuse integration fits together — the end-to-end flow, quote types, and resources.
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](/initial-setup).
## Integration Flow
The typical integration follows this pattern:
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](/guides/onboarding#hosted-ui) (fastest) or [Programmatic](/guides/onboarding#programmatic) (white-label). See [Onboarding Customers](/guides/onboarding) for details.
Discover which assets your customer can buy, sell, or swap. Use [GET /ramp/assets](/api-reference/assets/list-assets) (auth required, returns all rampable stablecoins and stablebonds for the chain, sorted by currency priority) or [GET /lookup/stablebonds](/api-reference/lookup/list-stablebonds) (public, all assets). Use the `identifier` field from the response when creating quotes.
Get pricing via [POST /ramp/quote](/api-reference/quotes/get-quote). Quotes expire after **2 minutes**. Key response fields:
| Field | Meaning |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `exchangeRate` | The customer-facing rate, **after fees**. |
| `nominalRate` | The pre-fee underlying rate (FX rate, or the bond/wrap rate). |
| `etherfuseMidMarketRate` | FX mid-market reference rate — present only for cross-currency (FX) quotes; absent on direct stablebond ramps. |
| `feeBps` / `feeAmount` | The fee in basis points and absolute amount (includes any Stellar wallet-setup cost). |
| `destinationAmount` | What the customer receives. |
| `requiresSwap` | `true` when the quote needs an on-chain swap. |
| `expiresAt` | Hard expiry — create the order before this. |
See the detailed guides for quote examples: [Onramps](/guides/testing-onramps), [Offramps](/guides/testing-offramps), [Swaps](/guides/testing-swaps).
Execute using the quote. For on/off-ramps, call [POST /ramp/order](/api-reference/orders/create-order) — the order inherits direction and amounts from the quote. For swaps, call [POST /ramp/swap](/api-reference/swaps/swap-assets).
See [Testing Onramps](/guides/testing-onramps), [Testing Offramps](/guides/testing-offramps), or [Testing Swaps](/guides/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](/api-reference/orders/cancel-order). Orders left unfunded **auto-cancel after 24 hours**, so abandoned orders clean themselves up.
Subscribe to webhooks via [POST /ramp/webhook](/api-reference/webhooks/create-webhook) to receive real-time updates. See [Webhooks](/webhooks) for event types, status flows, and scenarios.
***
## Quote Types
| Type | Source | Target | Use Case |
| --------- | -------------------------- | -------------------------- | ---------------------------------------- |
| `onramp` | Fiat | Tokens (USDC, CETES, etc.) | Customer buys tokens |
| `offramp` | Tokens (USDC, CETES, etc.) | Fiat | Customer sells tokens |
| `swap` | Token | Token | Customer exchanges one token for another |
***
## Supported markets, chains & assets
| | Coverage |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Live market** | Mexico — fiat **MXN** over SPEI. |
| **Upcoming markets** | Brazil (BRL), Korea (KRW), Argentina (ARS). See [Fees](/fees). |
| **On/off-ramp chains** | Solana, Stellar, Base, Polygon, Monad. |
| **Swap chains** | Stellar and Solana only (not yet on EVM). |
| **Embedded wallets** | Non-custodial wallets you provision and sign for programmatically, currently **Stellar only**. See [Embedded Wallets](/guides/embedded-wallets). |
| **Assets** | Yield-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](/guides/chains/solana), [Stellar](/guides/chains/stellar), [Base](/guides/chains/base), [Polygon](/guides/chains/polygon), [Monad](/guides/chains/monad).
**Always discover assets with [`GET /ramp/assets`](/api-reference/assets/list-assets)** (or the public [`GET /lookup/stablebonds`](/api-reference/lookup/list-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](/fees)** for the full breakdown.
***
## Webhooks
Etherfuse pushes signed, real-time events for orders, swaps, KYC, and bank accounts. See **[Webhooks](/webhooks)** for how delivery works, the full event catalog, the order/swap status flows, common scenarios, and best practices — and **[Verifying Webhooks](/guides/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](/api-reference/organizations/create-child-org) and renamed via [PUT /ramp/organization/\{org\_id}/name](/api-reference/organizations/rename-organization).
* **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](/api-reference/wallets/register-wallet) or scoped to a child org customer via [POST /ramp/customer/\{customer\_id}/wallet](/api-reference/wallets/register-customer-wallet).
* **Orders** (`orderId`) — Onramp and offramp transactions. You generate this UUID. The order-listing endpoints ([`GET`](/api-reference/orders/list-orders) / [`POST /ramp/orders`](/api-reference/orders/search-orders)) return on/off-ramps only — **swaps are not included** and are tracked separately via `swap_updated` webhooks.
* **Webhooks** — Event notification subscriptions.
***
## Troubleshooting
See the [Errors](/errors) reference for every status code and common error message (`Proxy account not found`, `Bank account not found`, `Quote expired`, …), and [Authentication](/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](/guides/testing-onramps#stellar-first-time-wallet-onramp) for the full flow. For offramps and swaps, the wallet must still have trust lines set up beforehand.