### GET /ramp/balances response example Source: https://docs.etherfuse.com/changelog Example JSON response for the wallet balances endpoint, showing asset identifiers, balances, and fiat/USD valuations. ```json { "walletId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "blockchain": "stellar", "publicKey": "GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL", "observedAt": "2026-09-04T18:00:00Z", "balances": [ { "symbol": "cetes", "identifier": "CETES:GC3CW7EDYV6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWN", "balance": "1500.00", "currency": "mxn", "amountInFiat": "25000.000000", "amountInUsd": "1450.000000" } ] } ``` -------------------------------- ### Create customer organization with POST /ramp/organization (Sandbox and Production) Source: https://docs.etherfuse.com/guides/kyc-websdk Creates a personal organization for the customer. The sandbox and production endpoints differ only by host. You must generate the customer UUID and include it as the `id`; the `userInfo.email` is required for verification. ```bash curl -X POST https://api.sand.etherfuse.com/ramp/organization \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "id": "", "displayName": "Ana Ejemplo", "accountType": "personal", "userInfo": { "email": "ana@example.com", "displayName": "Ana Ejemplo" } }' ``` ```bash curl -X POST https://api.etherfuse.com/ramp/organization \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "id": "", "displayName": "Ana Ejemplo", "accountType": "personal", "userInfo": { "email": "ana@example.com", "displayName": "Ana Ejemplo" } }' ``` -------------------------------- ### GET /lookup/restricted-countries JSON response example Source: https://docs.etherfuse.com/changelog Example JSON response from the restricted-country lookup endpoint. Returns a countries array with ISO alpha-2 code, name, and kyc/kyb booleans. Use to pre-check a country before onboarding or filter country selectors. ```json { "countries": [ { "code": "AF", "name": "Afghanistan", "kyc": true, "kyb": true } ] } ``` -------------------------------- ### Make your first authenticated call and list stablebonds Source: https://docs.etherfuse.com/quickstart Use the sandbox base URL https://api.sand.etherfuse.com and send your key in the Authorization header with no Bearer prefix. The first command performs a connectivity check on the /ramp endpoint; the second lists available stablebonds without authentication. ```bash curl https://api.sand.etherfuse.com/ramp \ -H "Authorization: " ``` ```bash curl https://api.sand.etherfuse.com/lookup/stablebonds ``` -------------------------------- ### OpenAPI specification for GET /ramp/verification/occupations Source: https://docs.etherfuse.com/api-reference/kyc/list-occupation-categories The OpenAPI 3.1.0 specification for the Etherfuse FX API, including the GET /ramp/verification/occupations endpoint. It shows the response schema with an example of occupation categories. The endpoint is part of the KYC tag and requires API key authentication. ```yaml openapi: 3.1.0 info: title: Etherfuse FX API description: Partner-facing ramp API for onramps, offramps, swaps, and KYC. license: name: Proprietary version: 1.0.0 servers: - url: https://api.sand.etherfuse.com description: Sandbox security: - ApiKeyAuth: [] tags: - name: Authentication description: >- Partner JWT authentication — exchange a JWT for an access token, or launch a user into the app. - name: Lookup description: >- Public reference data: exchange rates, stablebonds, bond costs, country codes. - name: Assets description: Rampable stablecoins and stablebonds available per blockchain. - name: Bank Accounts description: Register and retrieve customer bank accounts. - name: Quotes description: Price quotes for onramps, offramps, and swaps. - name: Orders description: Create, track, and manage ramp orders. - name: Swaps description: Crypto-to-crypto swaps. - name: Sponsored description: Token approvals for sponsored (gasless) offramps. - name: Customers description: Customer (child-organization) records. - name: Wallets description: Register and manage customer wallets. - name: KYC description: >- Submit a customer's verification data, documents and questionnaire answers, import a verification they already passed elsewhere, and check where their KYC stands. - name: Webhooks description: Event notification subscriptions. - name: Organizations description: Organization identity, child orgs, and partner fees. - name: Statements description: >- Monthly revenue share statements for closed months, as a list or as a CSV or PDF download. - name: Deprecated description: >- Endpoints kept working until their sunset date and then removed. See the deprecations page for replacements and dates. paths: /ramp/verification/occupations: get: tags: - KYC summary: List occupation categories description: >- The values [`POST /ramp/customer/{customer_id}/verification/questionnaire`](/api-reference/kyc/submit-a-verification-questionnaire) accepts for `industry`. Either the `code` or the `label` is submittable. The codes are opaque, so this is the only way to know them. Read live from the same definition the submission validates against, so the two cannot disagree. operationId: list_occupation_categories responses: '200': description: The accepted occupation categories. content: application/json: schema: type: object required: - occupations properties: occupations: type: array items: type: object required: - code - label properties: code: type: string description: The value to send as `industry`. label: type: string description: What the code means. Also accepted as `industry`. example: occupations: - code: '1000000' label: NOT APPLICABLE - code: '4430200' label: >- INFORMATION TECHNOLOGY - IT PROGRAMMING ENGINEERS OR TECHNICIANS components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: API key sent in the Authorization header. ``` -------------------------------- ### Example requirements breakdown response Source: https://docs.etherfuse.com/guides/onboarding The JSON response showing the status of individual requirements. The requiresLaunch flag indicates if the WebSDK is needed to satisfy the requirement. ```json { "customerId": "123e4567-e89b-12d3-a456-426614174000", "status": "in_progress", "requirements": [ { "type": "personal_data", "status": "satisfied", "requiresLaunch": false }, { "type": "identity_document", "status": "satisfied", "requiresLaunch": false }, { "type": "occupation", "status": "pending", "requiresLaunch": false }, { "type": "email_confirmation", "status": "pending", "requiresLaunch": true }, { "type": "selfie", "status": "pending", "requiresLaunch": true }, { "type": "customer_agreement", "status": "pending", "requiresLaunch": false } ] } ``` -------------------------------- ### OpenAPI specification for GET /ramp/customer/{customer_id} Source: https://docs.etherfuse.com/api-reference/customers/get-customer OpenAPI 3.1.0 specification for the Etherfuse FX API, including the GET /ramp/customer/{customer_id} endpoint. Defines the Customer schema with required fields and an example response. Requires an API key in the Authorization header. ```yaml openapi: 3.1.0 info: title: Etherfuse FX API description: Partner-facing ramp API for onramps, offramps, swaps, and KYC. license: name: Proprietary version: 1.0.0 servers: - url: https://api.sand.etherfuse.com description: Sandbox security: - ApiKeyAuth: [] tags: - name: Authentication description: >- Partner JWT authentication — exchange a JWT for an access token, or launch a user into the app. - name: Lookup description: >- Public reference data: exchange rates, stablebonds, bond costs, country codes. - name: Assets description: Rampable stablecoins and stablebonds available per blockchain. - name: Bank Accounts description: Register and retrieve customer bank accounts. - name: Quotes description: Price quotes for onramps, offramps, and swaps. - name: Orders description: Create, track, and manage ramp orders. - name: Swaps description: Crypto-to-crypto swaps. - name: Sponsored description: Token approvals for sponsored (gasless) offramps. - name: Customers description: Customer (child-organization) records. - name: Wallets description: Register and manage customer wallets. - name: KYC description: >- Submit a customer's verification data, documents and questionnaire answers, import a verification they already passed elsewhere, and check where their KYC stands. - name: Webhooks description: Event notification subscriptions. - name: Organizations description: Organization identity, child orgs, and partner fees. - name: Statements description: >- Monthly revenue share statements for closed months, as a list or as a CSV or PDF download. - name: Deprecated description: >- Endpoints kept working until their sunset date and then removed. See the deprecations page for replacements and dates. paths: /ramp/customer/{customer_id}: get: tags: - Customers summary: Get customer description: Retrieves details for a specific customer accessible to your API key. operationId: get_customer parameters: - name: customer_id in: path description: The customer ID required: true schema: type: string format: uuid responses: '200': description: The customer content: application/json: schema: $ref: '#/components/schemas/Customer' '404': description: No organization exists with that `customer_id`. components: schemas: Customer: type: object required: - customerId - createdAt - updatedAt properties: createdAt: type: string format: date-time description: Timestamp when the customer was created. customerId: type: string format: uuid description: Unique identifier for the customer. displayName: type: - string - 'null' description: Display name of the customer. updatedAt: type: string format: date-time description: Timestamp when the customer was last updated. example: createdAt: '2026-05-01T14:30:00Z' customerId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 displayName: Ana García updatedAt: '2026-05-02T09:15:00Z' securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: API key sent in the Authorization header. ``` -------------------------------- ### Install Stablebond SDKs (npm, yarn, cargo) Source: https://docs.etherfuse.com/sdks Install the Stablebond SDK for TypeScript/JavaScript with npm or yarn, or the Rust SDK with cargo. The TypeScript SDK is used for web and mobile apps; the Rust SDK provides typed access for Rust projects. ```bash npm install @etherfuse/stablebond-sdk ``` ```bash yarn add @etherfuse/stablebond-sdk ``` ```bash cargo add stablebond-sdk ``` -------------------------------- ### Occupation list response (JSON) Source: https://docs.etherfuse.com/guides/kyc-api Example response from `GET /ramp/verification/occupations`. Each entry is a `{ code, label }` pair; submit the `code` value, not the label. ```json { "occupations": [ { "code": "1000000", "label": "NOT APPLICABLE" }, { "code": "4430200", "label": "INFORMATION TECHNOLOGY - IT PROGRAMMING ENGINEERS OR TECHNICIANS" } ] } ``` -------------------------------- ### GET /ramp/assets response with metadata block Source: https://docs.etherfuse.com/changelog Example JSON response from GET /ramp/assets showing the new metadata block with canonical symbol, name, and image, plus the balance field as a human-decimal string (e.g., '1500.00'). The legacy top-level fields remain for backward compatibility. ```json { "assets": [ { "identifier": "CETES:GC3CW7EDYRTWQ635VDIGY6S4ZUF5L6TQ7AA4MWS7LEQDBLUSZXV7UPS4", "symbol": "CETES", "name": "Cetes", "image": "https://assets.etherfuse.com/cetes.png", "metadata": { "symbol": "CETES", "name": "Cetes", "image": "https://assets.etherfuse.com/cetes.png" }, "balance": "1500.00" } ] } ``` -------------------------------- ### Wallet provisioning response (200) Source: https://docs.etherfuse.com/guides/embedded-wallets Example JSON response from POST /ramp/wallet. Contains walletId, publicKey (Stellar address), blockchain, signerPublicKey, and claimedOwnership. Use publicKey as walletAddress and walletId as cryptoWalletId in subsequent orders. ```json { "walletId": "1b6e98a2-...", "publicKey": "GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL", "blockchain": "stellar", "signerPublicKey": "02a1...", "claimedOwnership": true } ``` -------------------------------- ### OpenAPI spec for Verify API key (GET /ramp) Source: https://docs.etherfuse.com/api-reference/organizations/verify-api-key OpenAPI specification for the Etherfuse FX API, including the GET /ramp endpoint that verifies an API key and returns the associated organization ID. The API key is sent in the Authorization header, and the response example shows an org_id UUID. ```yaml openapi: 3.1.0 info: title: Etherfuse FX API description: Partner-facing ramp API for onramps, offramps, swaps, and KYC. license: name: Proprietary version: 1.0.0 servers: - url: https://api.sand.etherfuse.com description: Sandbox security: - ApiKeyAuth: [] tags: - name: Authentication description: >- Partner JWT authentication — exchange a JWT for an access token, or launch a user into the app. - name: Lookup description: >- Public reference data: exchange rates, stablebonds, bond costs, country codes. - name: Assets description: Rampable stablecoins and stablebonds available per blockchain. - name: Bank Accounts description: Register and retrieve customer bank accounts. - name: Quotes description: Price quotes for onramps, offramps, and swaps. - name: Orders description: Create, track, and manage ramp orders. - name: Swaps description: Crypto-to-crypto swaps. - name: Sponsored description: Token approvals for sponsored (gasless) offramps. - name: Customers description: Customer (child-organization) records. - name: Wallets description: Register and manage customer wallets. - name: KYC description: >- Submit a customer's verification data, documents and questionnaire answers, import a verification they already passed elsewhere, and check where their KYC stands. - name: Webhooks description: Event notification subscriptions. - name: Organizations description: Organization identity, child orgs, and partner fees. - name: Statements description: >- Monthly revenue share statements for closed months, as a list or as a CSV or PDF download. - name: Deprecated description: >- Endpoints kept working until their sunset date and then removed. See the deprecations page for replacements and dates. paths: /ramp: get: tags: - Organizations summary: Verify API key description: |- Returns the organization ID associated with the API key. Useful for verifying credentials and connectivity. operationId: test_route responses: '200': description: The authenticated organization ID content: application/json: schema: {} example: org_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: API key sent in the Authorization header. ``` -------------------------------- ### Handle Wallet Provisioning Source: https://docs.etherfuse.com/guides/embedded-wallets-walkthrough Provisions a new wallet using the generated signer public key. ```javascript const handleProvision = async () => { if (!signerJwkRef.current || !signKeyRef.current) { alert('Generate a keypair first.'); return; } setBusy(true); setStep('provision', 'active'); const reqBody = { walletId: uuid(), signer: { signerPublicKeyJwk: signerJwkRef.current } }; try { const res = await apiFetch('POST', '/ramp/wallet', reqBody); setWalletId(res.walletId); setWalletAddress(res.publicKey); setStepLog('provision', { req: reqBody, res }); setStep('provision', 'done'); setStep('quote', 'active'); } catch (e) { setStepLog('provision', { req: reqBody, error: e.message }); setStep('provision', 'error'); } finally { setBusy(false); } }; ``` -------------------------------- ### Create an Order (Sandbox) Source: https://docs.etherfuse.com/guides/testing-onramps Create an order in the sandbox environment using the POST /ramp/order endpoint and a previously generated quoteId. ```bash curl -X POST https://api.sand.etherfuse.com/ramp/order \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "orderId": "", # You generate this UUID "bankAccountId": "", # From onboarding "cryptoWalletId": "", # From onboarding "quoteId": "" # From Step 2 }' ``` -------------------------------- ### OpenAPI specification for GET /lookup/exchange_rate Source: https://docs.etherfuse.com/api-reference/lookup/list-exchange-rates OpenAPI 3.1.0 specification for the Etherfuse FX API, including the public endpoint GET /lookup/exchange_rate. The endpoint returns exchange rates keyed by `usd_to_` with a per-provider `sources` breakdown. The specification includes the optional `max_age` query parameter and an example response. ```yaml openapi: 3.1.0 info: title: Etherfuse FX API description: Partner-facing ramp API for onramps, offramps, swaps, and KYC. license: name: Proprietary version: 1.0.0 servers: - url: https://api.sand.etherfuse.com description: Sandbox security: - ApiKeyAuth: [] tags: - name: Authentication description: >- Partner JWT authentication — exchange a JWT for an access token, or launch a user into the app. - name: Lookup description: >- Public reference data: exchange rates, stablebonds, bond costs, country codes. - name: Assets description: Rampable stablecoins and stablebonds available per blockchain. - name: Bank Accounts description: Register and retrieve customer bank accounts. - name: Quotes description: Price quotes for onramps, offramps, and swaps. - name: Orders description: Create, track, and manage ramp orders. - name: Swaps description: Crypto-to-crypto swaps. - name: Sponsored description: Token approvals for sponsored (gasless) offramps. - name: Customers description: Customer (child-organization) records. - name: Wallets description: Register and manage customer wallets. - name: KYC description: >- Submit a customer's verification data, documents and questionnaire answers, import a verification they already passed elsewhere, and check where their KYC stands. - name: Webhooks description: Event notification subscriptions. - name: Organizations description: Organization identity, child orgs, and partner fees. - name: Statements description: >- Monthly revenue share statements for closed months, as a list or as a CSV or PDF download. - name: Deprecated description: >- Endpoints kept working until their sunset date and then removed. See the deprecations page for replacements and dates. paths: /lookup/exchange_rate: get: tags: - Lookup summary: List exchange rates description: >- Returns current USD exchange rates for all supported currencies, each keyed by `usd_to_` with a per-provider `sources` breakdown. Public — no API key required. operationId: exchange_rates parameters: - name: max_age in: query description: >- Maximum age of a source in seconds. Sources whose `updated_at` timestamp is older than `now - max_age` are excluded from the `sources` map. When omitted, all sources are returned regardless of age. required: false schema: type: - integer - 'null' format: int64 minimum: 0 responses: '200': description: All exchange rates keyed by `usd_to_` content: application/json: schema: {} example: usd_to_brl: rate: '4.97' sources: provider_1: rate: '4.97' updated_at: 1709510400 updated_at: 1709510400 usd_to_mxn: rate: '17.15' sources: provider_1: rate: '17.15' updated_at: 1709510400 updated_at: 1709510400 security: - {} components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: API key sent in the Authorization header. ``` -------------------------------- ### OpenAPI Specification for Get Exchange Rate Endpoint Source: https://docs.etherfuse.com/api-reference/lookup/get-exchange-rate Defines the OpenAPI 3.1.0 API for the Etherfuse FX API, including the GET /lookup/exchange_rate/usd_to_{currency} endpoint. It includes the 'currency' path parameter and optional 'max_age' query parameter, with response examples for success (200) and error (404). No authentication is required. ```yaml openapi: 3.1.0 info: title: Etherfuse FX API description: Partner-facing ramp API for onramps, offramps, swaps, and KYC. license: name: Proprietary version: 1.0.0 servers: - url: https://api.sand.etherfuse.com description: Sandbox security: - ApiKeyAuth: [] tags: - name: Authentication description: >- Partner JWT authentication — exchange a JWT for an access token, or launch a user into the app. - name: Lookup description: >- Public reference data: exchange rates, stablebonds, bond costs, country codes. - name: Assets description: Rampable stablecoins and stablebonds available per blockchain. - name: Bank Accounts description: Register and retrieve customer bank accounts. - name: Quotes description: Price quotes for onramps, offramps, and swaps. - name: Orders description: Create, track, and manage ramp orders. - name: Swaps description: Crypto-to-crypto swaps. - name: Sponsored description: Token approvals for sponsored (gasless) offramps. - name: Customers description: Customer (child-organization) records. - name: Wallets description: Register and manage customer wallets. - name: KYC description: >- Submit a customer's verification data, documents and questionnaire answers, import a verification they already passed elsewhere, and check where their KYC stands. - name: Webhooks description: Event notification subscriptions. - name: Organizations description: Organization identity, child orgs, and partner fees. - name: Statements description: >- Monthly revenue share statements for closed months, as a list or as a CSV or PDF download. - name: Deprecated description: >- Endpoints kept working until their sunset date and then removed. See the deprecations page for replacements and dates. paths: /lookup/exchange_rate/usd_to_{currency}: get: tags: - Lookup summary: Get exchange rate description: |- Returns the current USD-to-specified-currency exchange rate, with a per-provider `sources` breakdown. Public — no API key required. operationId: usd_to_currency parameters: - name: currency in: path description: The target currency code (e.g. "mxn", "brl", "eur") required: true schema: type: string - name: max_age in: query description: >- Maximum age of a source in seconds. Sources whose `updated_at` timestamp is older than `now - max_age` are excluded from the `sources` map. When omitted, all sources are returned regardless of age. required: false schema: type: - integer - 'null' format: int64 minimum: 0 responses: '200': description: Exchange rate with per-provider source breakdown content: application/json: schema: {} example: rate: '17.15' sources: provider_1: rate: '17.15' updated_at: 1709510400 updated_at: 1709510400 '404': description: Currency is not supported security: - {} components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: API key sent in the Authorization header. ``` -------------------------------- ### Launch customer into /idv with JWT authentication Source: https://docs.etherfuse.com/guides/kyc-websdk Launches the customer into the hosted verification flow at `/idv`. The JWT `sub` must equal the org `id` from the creation step; otherwise a new person is registered and verification won't attach. Append `&lang=es` for Spanish and optionally pass a `return_url`. ```html
``` -------------------------------- ### GET /ramp/ws Source: https://docs.etherfuse.com/api-reference/websocket/connect-to-the-live-update-stream Opens a WebSocket that streams order_updated events for your organization. Authenticate with a token from POST /ramp/ws-api-token passed as the token query parameter; a browser cannot set an Authorization header on a WebSocket upgrade. The token is single-use and expires in 30 seconds. Each frame signals that an order changed; re-read the order with GET /ramp/order/{order_id} for the authoritative state, including any pending approval package. Connect over wss (for example wss://api.etherfuse.com/ramp/ws?token=...). ```APIDOC ## GET /ramp/ws ### Description Opens a WebSocket that streams `order_updated` events for your organization. Authenticate with a token from `POST /ramp/ws-api-token` passed as the `token` query parameter; a browser cannot set an `Authorization` header on a WebSocket upgrade. The token is single-use and expires in 30 seconds. Each frame signals that an order changed; re-read the order with `GET /ramp/order/{order_id}` for the authoritative state, including any pending approval package. Connect over `wss` (for example `wss://api.etherfuse.com/ramp/ws?token=...`). ### Method GET ### Endpoint /ramp/ws ### Parameters #### Query Parameters - **token** (string) - Required - Single-use, org-scoped token from POST /ramp/ws-api-token. Expires in 30 seconds. ### Response #### Success Response (101) - **description** - Switching Protocols: the connection is upgraded to a WebSocket and streams order_updated events. #### Error Response (400) - **description** - Missing, invalid, or expired token query parameter. ``` -------------------------------- ### Create Offramp Order with POST /ramp/order (Sandbox and Production) Source: https://docs.etherfuse.com/guides/testing-offramps Creates an offramp order in the sandbox or production environment. Requires a prior token approval for EVM chains and a funded Stellar wallet; the response includes a statusPage URL for signing the burn transaction. ```bash curl -X POST https://api.sand.etherfuse.com/ramp/order \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "orderId": "", # You generate this UUID "bankAccountId": "", # From onboarding "cryptoWalletId": "", # From onboarding "quoteId": "" # From Step 2 }' ``` ```bash curl -X POST https://api.etherfuse.com/ramp/order \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "orderId": "", # You generate this UUID "bankAccountId": "", # From onboarding "cryptoWalletId": "", # From onboarding "quoteId": "" # From Step 2 }' ``` -------------------------------- ### Submit with server-side hex (DER-wrapped signature) Source: https://docs.etherfuse.com/guides/embedded-wallets-walkthrough Example submission payload using the DER-wrapped signature (typical Node/Java signer). The approvalMessage is the exact fixture string, and the signature is the DER-wrapped hex. In production, approvalMessage and approvalMessageId come from a fresh GET /ramp/order/{orderId} read. ```json { "approvalMessageId": "5fac3ce6-b071-4265-de93-6fcf81a24d55", "approvalMessage": "{\"version\":\"1\",\"timestamp\":\"2026-06-18T12:00:00Z\",\"orderId\":\"4e9b2bd5-af60-4154-cd82-5ebf70913c44\"}", "publicKey": "03df2586b038e0aac461bca297b92cb1dd112e8b0fbcc19fb51cdeb653b003c76c", "signature": "304502205d5bfd6a52efdaadcd0ac2cff30fab2461b2484fd8e4dc4c894127aaa6678e86022100e814fc2404b1562a28d90121e540d6996e8484003790cd745fc78527ac07b766" } ```