Quickstart

Create and fund a sandbox onramp with this guide. First, create an API key under Account, then Manage Accounts in the sandbox dashboard. See Initial Setup for account setup and base URLs. Every request below uses the sandbox base URL https://api.sand.etherfuse.com and sends your key in the Authorization header, with no Bearer prefix (see Authentication).

Make your first call

Get your organization’s id. Payment account, quote and order routes take it as {organizationId}:

curl https://api.sand.etherfuse.com/me \
  -H "Authorization: <your_sandbox_api_key>"

{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "displayName": "Acme Inc", "approvedAt": "2026-04-15T12:00:00Z", "partnerFeeDefaultBps": 100 }

This guide acts for your own organization. To act for a customer, use the customer organization’s id instead. See Organizations in the route.List the organization’s payment accounts. A new organization has none yet:

curl https://api.sand.etherfuse.com/organization/<organization_id>/payment_accounts \
  -H "Authorization: <your_sandbox_api_key>"

{ "items": [], "totalItems": 0, "pageSize": 30, "pageNumber": 0, "totalPages": 0 }

A 401 with type ending in unauthorized means the key or the header is wrong. See Authentication.

Subscribe to order updates

Register the URL we send order events to. Store the secret from the response; we return it only once, and you need it to verify each delivery.

curl -X POST https://api.sand.etherfuse.com/webhook_subscription \
  -H "Authorization: <your_sandbox_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/etherfuse/webhooks", "eventType": "orderUpdated" }'

Webhook subscriptions do not take an organization id. One subscription covers your organization and every customer organization. Add a paymentAccountUpdated subscription the same way to hear when an account becomes ready. See Webhooks.

curl -X POST https://api.sand.etherfuse.com/organization/<organization_id>/payment_account \
  -H "Authorization: <your_sandbox_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "bank",
    "label": "Operating account",
    "country": "MX",
    "currency": "MXN",
    "accountDetails": { "kind": "clabe", "clabe": "012180000000000002" }
  }'

Then register the wallet the tokens go to:

curl -X POST https://api.sand.etherfuse.com/organization/<organization_id>/payment_account \
  -H "Authorization: <your_sandbox_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "wallet",
    "label": "Treasury wallet",
    "accountDetails": {
      "kind": "address",
      "address": "<your_testnet_wallet_address>",
      "chain": "stellar"
    }
  }'

Each response holds the account id and its rails. You can quote a direction once its status is ready. If a bank account returns 422 registration-info-required, add the fields listed in missing under registrationInfo and send it again. See Register payment accounts.

Find the asset to buy

List the tokens your wallet can receive. Use a token’s asset from the response in the quote.

curl "https://api.sand.etherfuse.com/supported_assets?paymentAccountId=<wallet_id>" \
  -H "Authorization: <your_sandbox_api_key>"

{
  "markets": [],
  "tokens": [
    {
      "asset": "CETES:GC3CW7EDYRTWQ635VDIGY6S4ZUF5L6TQ7AA4MWS7LEQDBLUSZXV7UPS4",
      "chain": "stellar",
      "currency": "MXN",
      "symbol": "CETES",
      "name": "Etherfuse CETES",
      "image": "https://assets.etherfuse.com/cetes.png"
    }
  ]
}

The bank account’s asset is its currency, MXN. See GET /supported_assets.

Get a quote

Price the transfer between the two accounts. Quotes expire after 2 minutes.

curl -X POST https://api.sand.etherfuse.com/organization/<organization_id>/quote \
  -H "Authorization: <your_sandbox_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "type": "stored", "id": "<bank_account_id>" },
    "destination": { "type": "stored", "id": "<wallet_id>" },
    "sourceAmount": "100",
    "sourceAsset": "MXN",
    "destinationAsset": "<asset_identifier>"
  }'

The response holds the quoteId, destinationAmount, rateAfterFees, feeBps and the fee lines in fees[]. Both accounts must belong to the organization in the route. See POST /organization/{organizationId}/quote.

Create the order

curl -X POST https://api.sand.etherfuse.com/organization/<organization_id>/order \
  -H "Authorization: <your_sandbox_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "quoteId": "<quote_id>" }'

The response is 201 with the order. Its id equals the quoteId, and sending the same quoteId again returns the same order (see Idempotency). fundingInstructions.destination says where the source sends the funds once it is available: a CLABE for a bank source, a blockchain address for a wallet source. An orderUpdated delivery tells you when it arrives.

Fund the order

How you fund the order depends on the source account.

Bank source (onramp)
Wallet source (offramp or swap)

In sandbox no real money moves. Simulate the customer’s SPEI payment:

curl -X POST https://api.sand.etherfuse.com/organization/<organization_id>/order/<order_id>/fiat_received \
  -H "Authorization: <your_sandbox_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "100" }'

See POST /organization/{organizationId}/order/{id}/fiat_received.

There is nothing to simulate: the wallet sends the tokens on the testnet. fundingInstructions.rail is the wallet’s chain, and fundingInstructions.destination holds the address to send to. Fund the order before fundingDeadline in one of two ways:

Sign the prepared transaction. When preparedTransaction is present, deserialize transaction, sign it with the wallet, and submit it to the network.
Send a transfer yourself. Send the order’s source.amount of source.asset to address, with memo when it is present.

{
  "fundingInstructions": {
    "rail": "stellar",
    "reference": "1000042",
    "fundingDeadline": "2026-10-07T12:30:00Z",
    "destination": {
      "address": "GBX3...",
      "expiresAt": null,
      "preparedTransaction": { "transaction": "AAAAAgAAAA...", "refreshAfter": "2026-10-07T12:30:00Z" }
    }
  }
}

An embedded wallet does not send anything itself: its owner approves the order’s authorization, and we move the funds.You need testnet tokens to fund from a wallet. Get them by running the bank-source onramp first. See Testnet tokens and the Offramps guide.

We detect the funds, then the order moves to funded and completed. An onramp can move to claimable instead, when the wallet has to claim the tokens (for example a Stellar wallet with no trustline yet). Each change sends an orderUpdated delivery with the full order.

Sandbox onramps are capped at 500 MXN per quote. See the Sandbox Reference.

Test other transfers

Onramp

Fiat to tokens. The customer pays MXN and receives tokens.

Offramp

Tokens to fiat. The customer sends tokens and receives MXN.

Swap

Token to token. The customer exchanges one asset for another.

Next steps

Onboard customers

Run KYC for your customers before they transact.

Monitor with webhooks

Get signed updates for orders, payment accounts and KYC instead of polling.

Understand the model

Payment accounts, rails, quotes, fees and order statuses.

Sandbox reference

Test KYC data, simulated deposits, and testnet tokens.

Migrating from v1

Follow the V1 → V2 guide to update an existing integration. Your API key, organizations, customers and KYC approvals remain valid.

Get Started

Migration

Concepts

User Authentication

Integration Guides

KYC

KYB

Blockchains

Resources

Test other transfers

Onramp

Offramp

Swap

Next steps

Onboard customers

Monitor with webhooks

Understand the model

Sandbox reference

Migrating from v1

​Test other transfers

Onramp

Offramp

Swap

​Next steps

Onboard customers

Monitor with webhooks

Understand the model

Sandbox reference

​Migrating from v1

Test other transfers

Next steps

Migrating from v1