> ## 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).

> [!NOTE]
>
> **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](https://docs.etherfuse.com/initial-setup.md).

## Integration Flow

The typical integration follows this pattern:

**1. Onboard Customer**

Create the customer's `personal` organization (you generate its `id`), then launch them into the hosted `/idv` flow, which handles identity verification **and** agreement signing in one step. Register their bank account and wallet via the API. See [KYC WebSDK](https://docs.etherfuse.com/guides/kyc-websdk.md) for that flow, or the [KYC Overview](https://docs.etherfuse.com/guides/onboarding.md) for what verification requires and the two API-driven alternatives.

**2. Get Available Assets**

Discover which assets your customer can buy, sell, or swap. Use [GET /ramp/assets](https://docs.etherfuse.com/api-reference/assets/list-assets.md) (auth required, returns all rampable stablecoins and stablebonds for the chain, sorted by currency priority) or [GET /lookup/stablebonds](https://docs.etherfuse.com/api-reference/lookup/list-stablebonds.md) (public, all assets). Use the `identifier` field from the response when creating quotes.

**3. Create Quote**

Get pricing via [POST /ramp/quote](https://docs.etherfuse.com/api-reference/quotes/get-quote.md). 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](https://docs.etherfuse.com/guides/testing-onramps.md), [Offramps](https://docs.etherfuse.com/guides/testing-offramps.md), [Swaps](https://docs.etherfuse.com/guides/testing-swaps.md).

**4. Create Order or Swap**

Execute using the quote. For on/off-ramps, call [POST /ramp/order](https://docs.etherfuse.com/api-reference/orders/create-order.md) — the order inherits direction and amounts from the quote. For swaps, call [POST /ramp/swap](https://docs.etherfuse.com/api-reference/swaps/swap-assets.md).

See [Testing Onramps](https://docs.etherfuse.com/guides/testing-onramps.md), [Testing Offramps](https://docs.etherfuse.com/guides/testing-offramps.md), or [Testing Swaps](https://docs.etherfuse.com/guides/testing-swaps.md) 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](https://docs.etherfuse.com/api-reference/orders/cancel-order.md). Orders left unfunded **auto-cancel after 24 hours**, so abandoned orders clean themselves up.

**5. Monitor via Webhooks**

Subscribe to webhooks via [POST /ramp/webhook](https://docs.etherfuse.com/api-reference/webhooks/create-webhook.md) to receive real-time updates. See [Webhooks](https://docs.etherfuse.com/webhooks.md) 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](https://docs.etherfuse.com/fees.md). |
| **On/off-ramp chains** | Solana, Stellar, Base, Polygon, Monad, Avalanche. |
| **Swap chains** | Stellar, Solana, and Monad. |
| **Embedded wallets** | Non-custodial wallets you provision and sign for programmatically, currently **Stellar only**. See [Embedded Wallets](https://docs.etherfuse.com/guides/embedded-wallets.md). |
| **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](https://docs.etherfuse.com/guides/chains/solana.md), [Stellar](https://docs.etherfuse.com/guides/chains/stellar.md), [Base](https://docs.etherfuse.com/guides/chains/base.md), [Polygon](https://docs.etherfuse.com/guides/chains/polygon.md), [Monad](https://docs.etherfuse.com/guides/chains/monad.md), [Avalanche](https://docs.etherfuse.com/guides/chains/avalanche.md).

> [!TIP]
>
> **Always discover assets with [`GET /ramp/assets`](https://docs.etherfuse.com/api-reference/assets/list-assets)** (or the public [`GET /lookup/stablebonds`](https://docs.etherfuse.com/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](https://docs.etherfuse.com/fees.md)** for the full breakdown.

***

## Webhooks

Etherfuse pushes signed, real-time events for orders, swaps, KYC, and bank accounts. See **[Webhooks](https://docs.etherfuse.com/webhooks.md)** for how delivery works, the full event catalog, the order/swap status flows, common scenarios, and best practices — and **[Verifying Webhooks](https://docs.etherfuse.com/guides/verifying-webhooks.md)** 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](https://docs.etherfuse.com/api-reference/organizations/create-child-org.md) and renamed via [PUT /ramp/organization/\{org\_id}/name](https://docs.etherfuse.com/api-reference/organizations/rename-organization.md).
* **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](https://docs.etherfuse.com/api-reference/wallets/register-wallet.md) or scoped to a child org customer via [POST /ramp/customer/\{customer\_id}/wallet](https://docs.etherfuse.com/api-reference/wallets/register-customer-wallet.md).
* **Orders** (`orderId`) — Onramp and offramp transactions. You generate this UUID. The order-listing endpoints ([`GET`](https://docs.etherfuse.com/api-reference/orders/list-orders) / [`POST /ramp/orders`](https://docs.etherfuse.com/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](https://docs.etherfuse.com/errors.md) reference for every status code and common error message (`Proxy account not found`, `Bank account not found`, `Quote expired`, …), and [Authentication](https://docs.etherfuse.com/authentication.md) 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](https://docs.etherfuse.com/guides/testing-onramps.md#stellar-first-time-wallet-onramp) for the full flow. For offramps and swaps, the wallet must still have trust lines set up beforehand.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.