Stablecoin on/off ramp

A stablecoin ramp is symmetric: on-ramp takes fiat in and delivers stablecoin to a wallet; off-ramp takes stablecoin in and delivers fiat to a bank. Both lean on the same v3 trade-and-settle calls, with the chain selection handled entirely by which verified withdrawal account you target.

When to reach for this

A fintech offering “USD → USDC on Solana” in-app
A merchant accepting USDC and settling to fiat on their bank cut-off
A treasury moving between fiat reserves and on-chain working capital

For a side-by-side comparison of all four patterns, see Integration patterns.

Setup

Verify the withdrawal account(s)

For an on-ramp, verify the stablecoin wallet on the chain you want to deliver to. For an off-ramp, verify the bank account that should receive the fiat. Both happen in the OpenFX dashboard. See Verified accounts for the walkthrough.

Confirm the chain

The network field on a stablecoin withdrawal account binds the chain. USDC on Solana and USDC on Ethereum are separate ledgers — see Supported networks for the full stablecoin × chain matrix. Pick the chain your end-user actually expects to receive on.

Subscribe to webhooks

Both flows benefit from the deposits event (so you react the moment funds arrive) and the withdrawals event (so your customer’s “your USDC is on Ethereum” message fires the second the on-chain tx confirms). Each webhook’s data is the resource object, so the terminal state is in data.status. See Webhooks setup.

On-ramp: fiat → stablecoin

1. Detect the fiat deposit

The customer’s wire arrives. OpenFX detects it (Deposit lifecycle) and either fires a webhook or you find it on GET /v3/fx/deposits. Match it to your internal user via the senderReference your customer was told to put in the wire memo.

curl "https://api.openfx.com/v3/fx/deposits?limit=25" \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE"

2. Quote USD → USDC

cURL

curl -X POST https://api.openfx.com/v3/fx/quotes \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "buyCurrency": "USDC",
    "sellCurrency": "USD",
    "sellAmount": "1000.00"
  }'

// Quotes a fiat <-> stablecoin conversion, anchored on the sell (funding)
// side — the pattern from /v3/examples/stablecoin-on-off-ramp#2-quote-usd-usdc.
// signRequest is the real helper from /v3/authentication — adjust this path
// if you've copied it somewhere else in your own project.
const { randomUUID } = require("node:crypto");
const { signRequest } = require("../../authentication/node/sign-request");
// Builds the POST /v3/fx/quotes body, anchored on the sell side — the
// customer is funding with an exact amount. Kept separate from the
// network call so it's testable without a real request.
function buildQuoteBody(buyCurrency, sellCurrency, sellAmount) {
  return { buyCurrency, sellCurrency, sellAmount };
}
async function quote(buyCurrency, sellCurrency, sellAmount) {
  const url = "https://api.openfx.com/v3/fx/quotes";
  const body = JSON.stringify(buildQuoteBody(buyCurrency, sellCurrency, sellAmount));
  const { headers } = signRequest({ method: "POST", url, body });
  headers["Idempotency-Key"] = randomUUID();
  const res = await fetch(url, { method: "POST", headers, body });
  const { data } = await res.json();
  return data;
}
module.exports = { buildQuoteBody, quote };
if (require.main === module) {
  // On-ramp: USD -> USDC, anchored on the $1000 the customer wired in.
  quote("USDC", "USD", "1000.00").catch((err) => {
    console.error("Error:", err.message);
    process.exitCode = 1;
  });
}

"""Quotes a fiat <-> stablecoin conversion, anchored on the sell (funding)
side — the pattern from
/v3/examples/stablecoin-on-off-ramp#2-quote-usd-usdc."""
import json
import os
import sys
import uuid
# sign_request is the real helper from /v3/authentication — adjust this path
# if you've copied it somewhere else in your own project.
sys.path.insert(
    0, os.path.join(os.path.dirname(__file__), "..", "..", "authentication", "python")
)
from sign_request import sign_request  # noqa: E402
import requests  # noqa: E402
def build_quote_body(buy_currency, sell_currency, sell_amount):
    """Builds the POST /v3/fx/quotes body, anchored on the sell side — the
    customer is funding with an exact amount. Kept separate from the
    network call so it's testable without a real request."""
    return {"buyCurrency": buy_currency, "sellCurrency": sell_currency, "sellAmount": sell_amount}
def quote(buy_currency, sell_currency, sell_amount):
    url = "https://api.openfx.com/v3/fx/quotes"
    body = json.dumps(build_quote_body(buy_currency, sell_currency, sell_amount)).encode("utf-8")
    headers, _ = sign_request("POST", url, body)
    headers["Idempotency-Key"] = str(uuid.uuid4())
    return requests.post(url, headers=headers, data=body).json()["data"]
if __name__ == "__main__":
    # On-ramp: USD -> USDC, anchored on the $1000 the customer wired in.
    print(quote("USDC", "USD", "1000.00"))

// Quotes a fiat <-> stablecoin conversion, anchored on the sell (funding)
// side — the pattern from
// /v3/examples/stablecoin-on-off-ramp#2-quote-usd-usdc. Uses only the
// built-in JDK APIs — no external dependency, so JSON serialization below
// is intentionally minimal (a flat object serializer), not a general
// JSON library.
import java.net.HttpURLConnection;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.UUID;
public class Quote {
    // Builds the POST /v3/fx/quotes body, anchored on the sell side — the
    // customer is funding with an exact amount. Kept separate from the
    // network call so it's testable without a real request.
    static Map<String, String> buildQuoteBody(String buyCurrency, String sellCurrency, String sellAmount) {
        Map<String, String> body = new LinkedHashMap<>();
        body.put("buyCurrency", buyCurrency);
        body.put("sellCurrency", sellCurrency);
        body.put("sellAmount", sellAmount);
        return body;
    }
    // Escapes a string for embedding in a JSON string literal. Sufficient
    // for this page's field values; not a general JSON serializer.
    static String escapeJson(String value) {
        StringBuilder out = new StringBuilder();
        for (int i = 0; i < value.length(); i++) {
            char c = value.charAt(i);
            switch (c) {
                case '"': out.append("\\\""); break;
                case '\\': out.append("\\\\"); break;
                case '\n': out.append("\\n"); break;
                case '\r': out.append("\\r"); break;
                case '\t': out.append("\\t"); break;
                default:
                    if (c < 0x20) out.append(String.format("\\u%04x", (int) c));
                    else out.append(c);
            }
        }
        return out.toString();
    }
    static String toJsonObject(Map<String, String> fields) {
        StringBuilder json = new StringBuilder("{");
        boolean first = true;
        for (Map.Entry<String, String> entry : fields.entrySet()) {
            if (!first) json.append(",");
            first = false;
            json.append("\"").append(entry.getKey()).append("\":\"").append(escapeJson(entry.getValue())).append("\"");
        }
        return json.append("}").toString();
    }
    static void quote(String buyCurrency, String sellCurrency, String sellAmount) throws Exception {
        String url = "https://api.openfx.com/v3/fx/quotes";
        byte[] body = toJsonObject(buildQuoteBody(buyCurrency, sellCurrency, sellAmount))
                .getBytes(StandardCharsets.UTF_8);
        // SignRequest is the real helper from /v3/authentication, compiled
        // on the classpath alongside this file — see that page's example.
        Map<String, String> headers = SignRequest.signRequest("POST", url, body);
        headers.put("Idempotency-Key", UUID.randomUUID().toString());
        HttpURLConnection conn = (HttpURLConnection) URI.create(url).toURL().openConnection();
        conn.setRequestMethod("POST");
        for (Map.Entry<String, String> h : headers.entrySet()) {
            conn.setRequestProperty(h.getKey(), h.getValue());
        }
        conn.setDoOutput(true);
        conn.getOutputStream().write(body);
        conn.getResponseCode();
    }
    public static void main(String[] args) throws Exception {
        // On-ramp: USD -> USDC, anchored on the $1000 the customer wired in.
        quote("USDC", "USD", "1000.00");
    }
}

// Quotes a fiat <-> stablecoin conversion, anchored on the sell (funding)
// side — the pattern from
// /v3/examples/stablecoin-on-off-ramp#2-quote-usd-usdc. Requires OpenSSL
// and libcurl.
#include <curl/curl.h>
#include <openssl/rand.h>
#include <iomanip>
#include <map>
#include <sstream>
#include <string>
// Matches the definition in ../../authentication/cpp/sign_request.cpp,
// compiled together with this file — see that file for the real
// implementation of signRequest.
struct SignedRequest {
    std::string authHeader;
    std::string sigHeader;
};
SignedRequest signRequest(const std::string& method, const std::string& urlPath,
                           const std::string& query, const std::string& body);
// Builds the POST /v3/fx/quotes body, anchored on the sell side — the
// customer is funding with an exact amount. Kept separate from the
// network call so it's testable without a real request.
std::map<std::string, std::string> buildQuoteBody(const std::string& buyCurrency, const std::string& sellCurrency,
                                                    const std::string& sellAmount) {
    return {{"buyCurrency", buyCurrency}, {"sellCurrency", sellCurrency}, {"sellAmount", sellAmount}};
}
// Escapes a string for embedding in a JSON string literal. Sufficient for
// this page's field values; not a general JSON serializer.
std::string escapeJson(const std::string& value) {
    std::ostringstream out;
    for (unsigned char c : value) {
        switch (c) {
            case '"': out << "\\\""; break;
            case '\\': out << "\\\\"; break;
            case '\n': out << "\\n"; break;
            case '\r': out << "\\r"; break;
            case '\t': out << "\\t"; break;
            default:
                if (c < 0x20) out << "\\u" << std::hex << std::setfill('0') << std::setw(4) << (int)c << std::dec;
                else out << (char)c;
        }
    }
    return out.str();
}
std::string toJsonObject(const std::map<std::string, std::string>& fields) {
    std::ostringstream json;
    json << "{";
    bool first = true;
    for (const auto& [key, value] : fields) {
        if (!first) json << ",";
        first = false;
        json << "\"" << key << "\":\"" << escapeJson(value) << "\"";
    }
    json << "}";
    return json.str();
}
// Generates a random per-call idempotency key. Not RFC 4122 UUID format —
// idempotency keys only need to be unique client-generated strings — but
// uses the same RAND_bytes source as the JWT nonce in sign_request.cpp.
std::string randomIdempotencyKey() {
    unsigned char bytes[16];
    RAND_bytes(bytes, sizeof(bytes));
    std::ostringstream hex;
    for (unsigned char b : bytes) hex << std::hex << std::setfill('0') << std::setw(2) << (int)b;
    return hex.str();
}
static size_t discard(char*, size_t s, size_t n, void*) { return s * n; }
void quote(const std::string& buyCurrency, const std::string& sellCurrency, const std::string& sellAmount) {
    std::string url = "https://api.openfx.com/v3/fx/quotes";
    std::string body = toJsonObject(buildQuoteBody(buyCurrency, sellCurrency, sellAmount));
    SignedRequest req = signRequest("POST", "/v3/fx/quotes", "", body);
    CURL* curl = curl_easy_init();
    curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, ("Authorization: " + req.authHeader).c_str());
    headers = curl_slist_append(headers, ("X-Request-Signature: " + req.sigHeader).c_str());
    headers = curl_slist_append(headers, ("Idempotency-Key: " + randomIdempotencyKey()).c_str());
    headers = curl_slist_append(headers, "Content-Type: application/json");
    curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, body.c_str());
    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, discard);
    curl_easy_perform(curl);
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
}
#ifndef QUOTE_NO_MAIN
#include <iostream>
int main() {
    try {
        // On-ramp: USD -> USDC, anchored on the $1000 the customer wired in.
        quote("USDC", "USD", "1000.00");
        return 0;
    } catch (const std::exception& e) {
        std::cerr << "Error: " << e.what() << std::endl;
        return 1;
    }
}
#endif

// Quotes a fiat <-> stablecoin conversion, anchored on the sell (funding)
// side — the pattern from
// /v3/examples/stablecoin-on-off-ramp#2-quote-usd-usdc.
package main
import (
	"bytes"
	"crypto/rand"
	"encoding/json"
	"fmt"
	"net/http"
	// auth is the real signRequest helper from /v3/authentication — see
	// go.mod's replace directive if you've copied it somewhere else.
	auth "openfx-v3-authentication-example"
)
type QuoteBody struct {
	BuyCurrency  string `json:"buyCurrency"`
	SellCurrency string `json:"sellCurrency"`
	SellAmount   string `json:"sellAmount"`
}
// Builds the POST /v3/fx/quotes body, anchored on the sell side — the
// customer is funding with an exact amount. Kept separate from the
// network call so it's testable without a real request.
func buildQuoteBody(buyCurrency, sellCurrency, sellAmount string) QuoteBody {
	return QuoteBody{BuyCurrency: buyCurrency, SellCurrency: sellCurrency, SellAmount: sellAmount}
}
func newIdempotencyKey() (string, error) {
	b := make([]byte, 16)
	if _, err := rand.Read(b); err != nil {
		return "", err
	}
	b[6] = (b[6] & 0x0f) | 0x40
	b[8] = (b[8] & 0x3f) | 0x80
	return fmt.Sprintf("%x-%x-%x-%x-%x", b[0:4], b[4:6], b[6:8], b[8:10], b[10:16]), nil
}
func quote(buyCurrency, sellCurrency, sellAmount string) error {
	url := "https://api.openfx.com/v3/fx/quotes"
	body, err := json.Marshal(buildQuoteBody(buyCurrency, sellCurrency, sellAmount))
	if err != nil {
		return err
	}
	signed, err := auth.SignRequest("POST", url, body)
	if err != nil {
		return err
	}
	key, err := newIdempotencyKey()
	if err != nil {
		return err
	}
	req, err := http.NewRequest("POST", url, bytes.NewReader(body))
	if err != nil {
		return err
	}
	for k, v := range signed.Headers {
		req.Header.Set(k, v)
	}
	req.Header.Set("Idempotency-Key", key)
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	return nil
}
func main() {
	// On-ramp: USD -> USDC, anchored on the $1000 the customer wired in.
	if err := quote("USDC", "USD", "1000.00"); err != nil {
		fmt.Println("Error:", err)
	}
}

#!/usr/bin/env bash
# Quotes a fiat <-> stablecoin conversion, anchored on the sell (funding)
# side — the pattern from
# /v3/examples/stablecoin-on-off-ramp#2-quote-usd-usdc. Illustrative only:
# cURL can't compute the ES256 request signature itself, so
# $OPENFX_JWT/$OPENFX_SIGNATURE below are placeholders — get real values
# from signRequest, in any supported language, via /v3/authentication.
set -euo pipefail
# On-ramp: USD -> USDC, anchored on the $1000 the customer wired in.
export OPENFX_JWT="<jwt-from-signRequest>"
export OPENFX_SIGNATURE="<signature-from-signRequest>"
curl -X POST https://api.openfx.com/v3/fx/quotes \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "buyCurrency": "USDC",
    "sellCurrency": "USD",
    "sellAmount": "1000.00"
  }'

3. Execute the trade

cURL

curl -X POST https://api.openfx.com/v3/fx/trades \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "quoteId": "'"$QUOTE_ID"'" }'

After execution, USD has decreased and USDC has increased in your balances. The chain doesn’t matter yet — USDC is one balance until you withdraw.

4. Withdraw to the customer’s chain-specific wallet

The withdrawalAccountId selects both currency (USDC) and chain (Solana). You don’t pass a network field — it’s bound to the account.

curl -X POST https://api.openfx.com/v3/fx/withdrawals \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "withdrawalAccountId": "a2c7d4f1-3b18-4f6a-9c35-2e8a1b4d9f02",
    "withdrawalAmount": "1000.00",
    "currency": "USDC"
  }'

The withdrawal reaches COMPLETED once the chain reaches the configured confirmation count. The response carries network and transactionHash so you can surface the chain explorer link to your user. See Supported networks for per-chain request examples (Ethereum, Solana, Tron, BSC, etc.).

Off-ramp: stablecoin → fiat

1. Receive the stablecoin deposit

The customer sends USDC to your OpenFX deposit address. The deposit record’s network tells you which chain it landed on; transactionHash is the on-chain reference for support tickets.

curl "https://api.openfx.com/v3/fx/deposits?limit=25" \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE"

Wait for status: "COMPLETED" — that’s when the funds are spendable. A stablecoin deposit appears as PENDING the moment OpenFX observes the on-chain transfer, then COMPLETED once it clears (or ERROR if it doesn’t). See Deposit lifecycle.

2. Quote USDC → USD

Same shape, opposite direction:

curl -X POST https://api.openfx.com/v3/fx/quotes \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "buyCurrency": "USD",
    "sellCurrency": "USDC",
    "sellAmount": "1000.00"
  }'

3. Execute the trade

Same POST /v3/fx/trades as the on-ramp. After execution, USDC has decreased and USD has increased.

4. Withdraw to the customer’s bank account

curl -X POST https://api.openfx.com/v3/fx/withdrawals \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "withdrawalAccountId": "8ff46b97-5742-4196-88dd-db7b0b46ab7a",
    "withdrawalAmount": "1000.00",
    "currency": "USD",
    "metadata": { "reconId": "Off-ramp 9f2b" }
  }'

The rail (Fed Wire vs SWIFT vs SEPA vs SPEI) is bound to the bank account. See Settlement times for cut-offs.

Choosing the right chain on on-ramps

When your UX lets a user pick the chain to receive on, the choice matters:

Chain	Typical confirm time	Fee profile	When to default to it
Solana	Seconds	Very low	Consumer apps, micro-payments
Base / Polygon	Seconds–minutes	Low	EVM tooling, low-cost EVM users
Ethereum	Minutes	Higher	Treasury, DeFi integration, broadest compatibility
Tron	Seconds	Low	USDT-heavy flows, especially in EM corridors

The full chain matrix per stablecoin (USDC, USDT, EURC) is at Supported networks.

Common mistakes

Treating “USDC” as one chain. A withdrawal to a Solana wallet can’t be sent on an Ethereum withdrawalAccountId — they’re separate addresses, separate ledgers. Confirm the verified withdrawal account’s network matches the user’s expectation before withdrawing. Sending to the wrong-chain address is not recoverable.
Quoting before the deposit clears. A PENDING deposit isn’t usable balance yet. Wait for COMPLETED (or for the webhook) before issuing the quote.
Polling chain explorers instead of GET /v3/fx/withdrawals/{id}. OpenFX’s own state machine is the source of truth; the explorer’s view can lag (or, for some chains, race ahead before OpenFX considers it confirmed).
Quoting first, then realizing the wallet isn’t verified. Set up the verified withdrawal account before the user’s first on-ramp; the quote → trade → withdrawal chain assumes the account is already in place.

What’s next

Supported networks

Stablecoin × chain matrix + per-chain request bodies.

Settlement times

Fiat-rail cut-offs by currency.

Deposit lifecycle

How deposits get from observed → credited.

Cross-border payments

The fiat-only sibling of this flow.

​When to reach for this

​Setup

​On-ramp: fiat → stablecoin

​1. Detect the fiat deposit

​2. Quote USD → USDC

​3. Execute the trade

​4. Withdraw to the customer’s chain-specific wallet

​Off-ramp: stablecoin → fiat

​1. Receive the stablecoin deposit

​2. Quote USDC → USD

​3. Execute the trade

​4. Withdraw to the customer’s bank account

​Choosing the right chain on on-ramps

​Common mistakes

​What’s next

Supported networks

Settlement times

Deposit lifecycle

Cross-border payments

When to reach for this

Setup

On-ramp: fiat → stablecoin

1. Detect the fiat deposit

2. Quote USD → USDC

3. Execute the trade

4. Withdraw to the customer’s chain-specific wallet

Off-ramp: stablecoin → fiat

1. Receive the stablecoin deposit

2. Quote USDC → USD

3. Execute the trade

4. Withdraw to the customer’s bank account

Choosing the right chain on on-ramps

Common mistakes

What’s next