Overview

This API allows you to integrate crypto on/off ramps into your application. Your customers can buy crypto with fiat (onramp) or sell crypto for fiat (offramp).

Integration Flow

The typical integration follows this pattern:

Onboard Customer
Get Assets
Create Quote
Create Order
Monitor Order via Webhooks

1. Onboard Customer

Generate a presigned URL and have your customer complete KYC verification.

POST /ramp/onboarding-url

{
  "customerId": "your-customer-uuid",
  "bankAccountId": "bank-account-uuid",
  "publicKey": "GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL",
  "blockchain": "stellar"
}

The customer visits the returned presignedUrl to complete identity verification and link their bank account. You’ll receive a customer_updated webhook when verification is complete.

2. Get Available Assets

Call /ramp/assets to show your user which assets they can buy or sell.

GET /ramp/assets?blockchain=stellar&currency=mxn&wallet=GDUKMGUGD3V6...

Response:

{
  "assets": [
    {
      "symbol": "USDC",
      "identifier": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "name": "USD Coin",
      "currency": "mxn",
      "balance": "100.50",
      "image": "https://example.com/usdc.png"
    },
    {
      "symbol": "CETES",
      "identifier": "CETES:GCRYUGD5NVARGXT56XEZI5CIFCQETYHAPQQTHO203IQZTHDHH4LATMYWC",
      "name": "CETES",
      "currency": "mxn",
      "balance": "50.00",
      "image": "https://example.com/cetes.png"
    }
  ]
}

Use the identifier field when creating quotes.

3. Create Quote

Get pricing for the conversion. Quotes expire after 2 minutes.

POST /ramp/quote

Onramp (buying USDC with MXN):

{
  "quoteId": "844393ca-be57-4817-a58a-5b60e2792c10",
  "customerId": "34fcc67a-2454-4578-8435-e2bf03b4dc30",
  "blockchain": "stellar",
  "quoteAssets": {
    "type": "onramp",
    "sourceAsset": "MXN",
    "targetAsset": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
  },
  "sourceAmount": "1000"
}

Offramp (selling USDC for MXN):

{
  "quoteId": "a44393ca-be57-4817-a58a-5b60e2792c12",
  "customerId": "34fcc67a-2454-4578-8435-e2bf03b4dc30",
  "blockchain": "stellar",
  "quoteAssets": {
    "type": "offramp",
    "sourceAsset": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
    "targetAsset": "MXN"
  },
  "sourceAmount": "50"
}

Quote Response:

{
  "quoteId": "844393ca-be57-4817-a58a-5b60e2792c10",
  "blockchain": "stellar",
  "quoteAssets": {
    "type": "onramp",
    "sourceAsset": "MXN",
    "targetAsset": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
  },
  "sourceAmount": "1000",
  "destinationAmount": "49.50",
  "destinationAmountAfterFee": "49.40",
  "feeBps": "20",
  "feeAmount": "2.00",
  "exchangeRate": "0.0495",
  "expiresAt": "2025-12-17T18:31:46.195307961Z"
}

4. Create Order

Execute the order using the quote. The order inherits the direction and amounts from the quote.

POST /ramp/order

{
  "orderId": "your-order-uuid",
  "bankAccountId": "bank-account-uuid",
  "publicKey": "GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL",
  "quoteId": "844393ca-be57-4817-a58a-5b60e2792c10"
}

Response (Onramp):

{
  "onramp": {
    "orderId": "your-order-uuid",
    "depositClabe": "646180157034567890",
    "depositAmount": 1000.00
  }
}

Response (Offramp):

{
  "offramp": {
    "orderId": "your-order-uuid"
  }
}

For onramps, the customer deposits MXN to the depositClabe. For offramps, the customer signs the burnTransaction returned in the webhook to send their crypto.

5. Monitor Order via Webhooks

After creating an order, monitor its progress via webhooks. Onramp:

The customer must send MXN to the depositClabe returned in the create order response
Once we confirm receipt of the fiat, you receive order_funded
We mint/transfer crypto and send it to the customer’s wallet
You receive order_completed with confirmedTxSignature containing the blockchain transaction hash

Offramp:

You receive order_created with burnTransaction containing an encoded transaction
Have the customer sign and submit the transaction to the blockchain
Once confirmed on-chain, you receive order_funded
We send MXN to the customer’s bank account
You receive order_completed

Swap (crypto to crypto):

Create a quote with type: "swap" specifying source and target crypto assets
Call /ramp/swap with the quoteId to initiate the swap
You receive swap_updated webhook with transaction to sign
Have the customer sign and submit the transaction
You receive swap_updated when completed

If a transaction expires before submission, use /ramp/order/{order_id}/regenerate_tx or /ramp/swap/{order_id}/regenerate_tx to get a new transaction. See the Webhooks section below for detailed payload examples.

Fees

Fees for onramps and offramps are based on your rolling 30-day transaction volume. Higher volume means lower fees.

30-Day Volume (USD)	Fee
0 - 5 million	20 bps (0.20%)
5 - 10 million	15 bps (0.15%)
10 - 50 million	10 bps (0.10%)
50 - 100 million	8 bps (0.08%)
100 million+	5 bps (0.05%)

The fee is calculated on the output amount and included in the quote response (feeBps, feeAmount, destinationAmountAfterFee). Your current fee tier is applied automatically when you create a quote.

Quote Types

Type	Source	Target	Use Case
`onramp`	Fiat (MXN)	Crypto (USDC, CETES)	Customer buys crypto
`offramp`	Crypto (USDC, CETES)	Fiat (MXN)	Customer sells crypto
`swap`	Crypto	Crypto	Customer exchanges one crypto for another

Webhooks

Subscribe to webhooks to receive real-time updates. Webhook payloads are signed with HMAC-SHA256 using your webhook secret. The signature is in the X-Signature header as sha256={hex_signature}.

Event Types

Event Type	Description
`customer_updated`	KYC verification status changed
`bank_account_updated`	Bank account verification status changed
`order_updated`	Order status changed
`swap_updated`	Swap transaction status changed

Webhook Status Values

Each webhook includes a status field indicating what triggered the event: Order statuses (order_updated):

order_created - Order has been created
order_funded - Order has been funded (fiat received for onramp, crypto confirmed for offramp)
order_completed - Order completed successfully
order_failed - Order failed
order_refunded - Order was refunded (onramp only)
order_canceled - Order was canceled

Customer statuses (customer_updated):

customer_pending - Customer verification in progress
customer_verified - Customer successfully verified
customer_failed - Customer verification failed

Bank account statuses (bank_account_updated):

bank_account_pending - Bank account verification pending
bank_account_awaiting_deposit_verification - Waiting for deposit verification
bank_account_active - Bank account is active and ready to use
bank_account_inactive - Bank account is inactive

Swap statuses (swap_updated):

swap_created - Swap has been created
swap_completed - Swap completed successfully
swap_failed - Swap failed

Order Status Flow

Orders progress through different statuses. You’ll receive an order_updated webhook at each transition. Onramp Order Flow (customer buys crypto with MXN):

created → funded → completed
    ↓        ↓
  failed   refunded
    ↓
 canceled

created - Order created, waiting for customer to deposit MXN to the depositClabe
funded - MXN deposit received and confirmed
completed - Crypto sent to customer’s wallet (confirmedTxSignature contains the tx hash)

Offramp Order Flow (customer sells crypto for MXN):

created → funded → completed
    ↓        ↓
  failed   failed
    ↓
 canceled

created - Order created, burnTransaction contains the transaction for the customer to sign
funded - Customer’s crypto transaction confirmed on-chain
completed - MXN sent to customer’s bank account

Swap Flow (customer exchanges crypto for crypto):

created → funded → completed
    ↓        ↓
  failed   failed

created - Swap created, transaction ready for customer to sign
funded - Customer’s crypto transaction confirmed on-chain
completed - Target crypto sent to customer’s wallet

Alternative Statuses:

failed - Order/swap failed (timeout, error, etc.)
refunded - Funds returned to customer (onramp only)
canceled - Order canceled before funding

Webhook Payload Examples

Order Created (Onramp):

{
  "order_updated": {
    "orderId": "123e4567-e89b-12d3-a456-426614174000",
    "customerId": "123e4567-e89b-12d3-a456-426614174001",
    "walletId": "223e4567-e89b-12d3-a456-426614174002",
    "bankAccountId": "323e4567-e89b-12d3-a456-426614174003",
    "orderType": "onramp",
    "status": "created",
    "amountInFiat": 1000.00,
    "depositClabe": "646180157034567890",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T10:00:00Z",
    "statusPage": "https://status.etherfuse.com/order/123e4567-e89b-12d3-a456-426614174000"
  }
}

Order Funded (Onramp):

{
  "order_updated": {
    "orderId": "123e4567-e89b-12d3-a456-426614174000",
    "customerId": "123e4567-e89b-12d3-a456-426614174001",
    "walletId": "223e4567-e89b-12d3-a456-426614174002",
    "bankAccountId": "323e4567-e89b-12d3-a456-426614174003",
    "orderType": "onramp",
    "status": "funded",
    "amountInFiat": 1000.00,
    "amountInTokens": 49.50,
    "depositClabe": "646180157034567890",
    "feeBps": 20,
    "feeAmountInFiat": 2.00,
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T10:05:00Z",
    "statusPage": "https://status.etherfuse.com/order/123e4567-e89b-12d3-a456-426614174000"
  }
}

Order Completed (Onramp):

{
  "order_updated": {
    "orderId": "123e4567-e89b-12d3-a456-426614174000",
    "customerId": "123e4567-e89b-12d3-a456-426614174001",
    "walletId": "223e4567-e89b-12d3-a456-426614174002",
    "bankAccountId": "323e4567-e89b-12d3-a456-426614174003",
    "orderType": "onramp",
    "status": "completed",
    "amountInFiat": 1000.00,
    "amountInTokens": 49.50,
    "confirmedTxSignature": "3Kz8V2xYm9...abc123",
    "depositClabe": "646180157034567890",
    "feeBps": 20,
    "feeAmountInFiat": 2.00,
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T10:10:00Z",
    "completedAt": "2025-01-15T10:10:00Z",
    "statusPage": "https://status.etherfuse.com/order/123e4567-e89b-12d3-a456-426614174000"
  }
}

Order Created (Offramp):

{
  "order_updated": {
    "orderId": "423e4567-e89b-12d3-a456-426614174000",
    "customerId": "123e4567-e89b-12d3-a456-426614174001",
    "walletId": "223e4567-e89b-12d3-a456-426614174002",
    "bankAccountId": "323e4567-e89b-12d3-a456-426614174003",
    "orderType": "offramp",
    "status": "created",
    "amountInTokens": 50.00,
    "burnTransaction": "AQAAAA...encoded_transaction_for_user_to_sign",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T10:00:00Z",
    "statusPage": "https://status.etherfuse.com/order/423e4567-e89b-12d3-a456-426614174000"
  }
}

Order Completed (Offramp):

{
  "order_updated": {
    "orderId": "423e4567-e89b-12d3-a456-426614174000",
    "customerId": "123e4567-e89b-12d3-a456-426614174001",
    "walletId": "223e4567-e89b-12d3-a456-426614174002",
    "bankAccountId": "323e4567-e89b-12d3-a456-426614174003",
    "orderType": "offramp",
    "status": "completed",
    "amountInTokens": 50.00,
    "amountInFiat": 1000.00,
    "confirmedTxSignature": "5Mz9X3yAn1...ghi789",
    "feeBps": 20,
    "feeAmountInFiat": 2.00,
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T10:15:00Z",
    "completedAt": "2025-01-15T10:15:00Z",
    "statusPage": "https://status.etherfuse.com/order/423e4567-e89b-12d3-a456-426614174000"
  }
}

Swap Created:

{
  "swap_updated": {
    "orderId": "523e4567-e89b-12d3-a456-426614174000",
    "customerId": "123e4567-e89b-12d3-a456-426614174001",
    "sendTransaction": "AQAAAA...encoded_transaction_for_user_to_sign",
    "sendTransactionHash": "",
    "status": "created",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T10:00:00Z"
  }
}

Swap Completed:

{
  "swap_updated": {
    "orderId": "523e4567-e89b-12d3-a456-426614174000",
    "customerId": "123e4567-e89b-12d3-a456-426614174001",
    "sendTransaction": "AQAAAA...encoded_tx",
    "sendTransactionHash": "4Lz9W3yZn0...def456",
    "receiveTransactionHash": "5Mz0X4zAo1...ghi789",
    "status": "completed",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T10:02:00Z"
  }
}

Resources

The API manages these resources:

Customers - Your end users who complete KYC
Bank Accounts - Mexican bank accounts linked to customers
Wallets - Crypto wallets associated with customers
Orders - Onramp and offramp transactions
Webhooks - Event notification subscriptions

Get Started

API Reference

Sandbox API Reference

Integration Flow

1. Onboard Customer

2. Get Available Assets

3. Create Quote

4. Create Order

5. Monitor Order via Webhooks

Fees

Quote Types

Webhooks

Event Types

Webhook Status Values

Order Status Flow

Webhook Payload Examples

Resources

Get Started

API Reference

Sandbox API Reference

​Integration Flow

​1. Onboard Customer

​2. Get Available Assets

​3. Create Quote

​4. Create Order

​5. Monitor Order via Webhooks

​Fees

​Quote Types

​Webhooks

​Event Types

​Webhook Status Values

​Order Status Flow

​Webhook Payload Examples

​Resources

Integration Flow

1. Onboard Customer

2. Get Available Assets

3. Create Quote

4. Create Order

5. Monitor Order via Webhooks

Fees

Quote Types

Webhooks

Event Types

Webhook Status Values

Order Status Flow

Webhook Payload Examples

Resources