Changelog - Etherfuse API

BreakingImproved

Catch-up on compliance and KYC status changes: bank accounts now require an approved organization, and KYC status is now a single 5-state value.

Breaking: Bank accounts require an approved organization

POST /ramp/customer/{customer_id}/bank-account and the presigned bank-account path now reject requests for unapproved personal organizations. Create the child organization with POST /ramp/organization, complete identity or business verification, and wait for the organization to be approved before registering a Mexican bank account. The partner dashboard also gates the bank-account step until verification is complete.

POST /ramp/organization no longer creates a bank account inline and no longer returns bankAccount in the response. Register bank accounts separately after the organization is approved. See Customer Onboarding (KYC) and Bank account creation.

KYC status is now a single 5-state value

GET /ramp/customer/{customer_id}/kyc and the kyc_updated webhook now publish a unified status field: not_started, in_progress, submitted, approved, or denied. The boolean approved field is still present for backward compatibility. If you were parsing the previous status strings, replace proposed with submitted and use denied for rejections or revoked approvals. See Verifying webhooks.

NewImprovedFixed

Principal Tokens are now supported across every chain; /idv onboarding handles addresses without postal codes and verifies email earlier.

Principal Tokens supported on all chains

MEXe, GBRe, and the full Principal Token family are now available for swaps and bridging across every chain Etherfuse supports — Solana, Stellar, Base, Polygon, and Monad. Create a POST /ramp/quote with quoteAssets.type: "swap" and the PT asset identifier from GET /ramp/assets, then execute with POST /ramp/swap. See the swaps guide and the chain guides for Stellar, Solana, Base, Polygon, and Monad.

`/idv` accepts addresses without postal codes

The hosted identity verification flow now completes for customers in countries that do not require a postal code. The address collected during /idv is accepted with the fields that are present, so onboarding no longer gets stuck waiting for a postcode. See Customer Onboarding (KYC).

`/idv` marks email verified earlier

Customers launched through /idv are now marked email-verified as soon as they complete the email verification step, instead of waiting until full KYC approval. This lets them continue through the rest of onboarding while the remaining verification completes. See User Launch Flows.

ImprovedDeprecated

Customer onboarding consolidates onto a single hosted /idv flow; presigned onboarding URL and programmatic KYC endpoints deprecated.

One onboarding flow: create org, launch `/idv`

Customer onboarding is now a single hosted flow. Create the customer’s personal organization (you generate its id), then launch them into /idv with scope: verification and sub = the org id. /idv runs identity verification and agreement signing in one hosted step. You no longer submit identity fields, upload ID images, or run a separate /agreements launch. Register the customer’s wallet and bank account over the API before or after. See Customer Onboarding (KYC).The partner-facing kyc_updated webhook and GET /ramp/customer/{customer_id}/kyc status endpoint are unchanged; keep using them to track approval.

Deprecated

The following are deprecated with a sunset date of August 16, 2026 (see the Deprecations page and the deprecation policy):

Presigned onboarding URL (POST /ramp/onboarding-url) and using the presigned URL for auth (e.g. POST /ramp/onboarding/bank-accounts).
Programmatic KYC submission (POST /ramp/customer/{customer_id}/kyc).
The /agreements launch: agreement signing now happens inside /idv.

KYC document upload (POST /ramp/customer/{customer_id}/kyc/documents) is also deprecated but has no sunset date yet.Migrate to the /idv launch above.

NewImproved

MEXe on Base/EVM chains, USTRY/EUROB/KTB swaps, canonical asset metadata, restricted-country lookup, and KYB legal name.

MEXe fiat ramps on Base and EVM chains

MEXe, the principal token backed by CETES, is now available for fiat on- and off-ramps on Base and the other EVM chains where the MEXe OFT is registered. Call POST /ramp/quote with blockchain: "base" (or monad, polygon) and the MEXe asset identifier from GET /ramp/assets, then create the order with POST /ramp/order. Cross-chain LayerZero OFT delivery is handled end-to-end, so the customer receives MEXe in their 0x wallet for onramps or sends from it for offramps. See the Base chain guide and the onramp and offramp testing guides.

Canonical asset metadata on GET /ramp/assets

GET /ramp/assets now returns a metadata block for every asset with the canonical symbol, name, and image from Solana Metaplex. The legacy top-level symbol, name, and image fields are still present for backward compatibility, but the new metadata block is the single source of truth for display metadata across all chains. The balance field is now a human-decimal string scaled by token decimals on every chain.

{
  "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"
    }
  ]
}

The metadata object is the recommended place to read symbol, name, and image. The balance value is now a human-decimal string such as 1500.00 everywhere, not a raw integer amount.

USTRY, EUROB, and KTB now available for swaps

The USTRY, EUROB, and KTB stablebonds are now eligible for crypto-to-crypto swap quotes on chains with DEX liquidity. They appear in the receive list from GET /ramp/assets and can be used as targetAsset or sourceAsset in a POST /ramp/quote with quoteAssets.type: "swap". If no swap route is available, the quote returns the existing 424 FailedToGetQuote response. See the swaps guide.

Restricted-country lookup endpoint

The new GET /lookup/restricted-countries endpoint lists countries with effective KYC or KYB restrictions. It returns a countries array with ISO alpha-2 code, name, kyc, and kyb booleans. Use it to pre-check a country before onboarding or to filter country selectors in your UI.

{
  "countries": [
    {
      "code": "AF",
      "name": "Afghanistan",
      "kyc": true,
      "kyb": true
    }
  ]
}

A country is included when KYC, KYB, or both are restricted. Country codes in the response are the same ISO alpha-2 codes used by GET /lookup/country-codes.

KYB legal name separate from organization display name

When you create a child organization with POST /ramp/organization, you can now pass legalName together with country to set the KYB company name independently of displayName. The legalName is the legal entity name used for compliance; displayName is the friendly org label. Renaming one does not affect the other. See the KYB guide.

New

Swap USDC to and from MEXe on Solana

MEXe, the Principal Token backed by CETES, is now live on Solana mainnet, and you can swap directly between USDC and MEXe in a single atomic transaction. Create a POST /ramp/quote with quoteAssets.type: "swap", sourceAsset set to the USDC mint and targetAsset set to the MEXe mint; the FX conversion between USDC and CETES is handled for you. The quote returns requiresSwap: true with the exchangeRate and destinationAmount, and you execute it like any other swap. See the swaps guide and the Solana chain guide.

Self-serve JWT auth configuration

You can now register the issuer and JWKS URL used to verify your partner-signed JWTs directly from the Etherfuse dashboard, instead of sending them to your Etherfuse representative. Set them once per environment (sandbox and production each keep their own registration), and Etherfuse fetches your JWKS from that URL to verify incoming tokens. See JWT authentication.

NewImproved

KYB partner API

Partners can now manage business organization membership and track KYB progress through the API. Create an org with POST /ramp/organization, then add, list, and remove members. Track completion with GET /ramp/organization/{id}/kyb/progress or subscribe to the new kyb_updated webhook to skip polling. See the KYB guide for the full walkthrough.

Business identity verification via /idv

The /idv launch flow now supports business customers. Personal customers still run a liveness face scan matched against their existing KYC ID. Business customers, who have no prior ID on file, complete a full ID document scan and face capture in a single session. The trigger is unchanged: a bank account with requiresAdditionalVerification: true. See User Launch Flows.

IDV Spanish localization

Append lang=es to the /idv launch target to render the entire identity verification flow in Spanish, including all UI text, scan prompts, and error messages. Omit the parameter or pass lang=en for English. Example target: /idv?bank_account_id=<uuid>&lang=es. See User Launch Flows.

NewImproved

Embedded wallets

Partners can now provision non-custodial wallets for their users via POST /ramp/wallet and move on-chain assets without managing gas, trustlines, or transaction construction. Each wallet is secured by a P-256 owner key that the partner (or their end-user) holds; Etherfuse proposes transactions and the owner signs one approval per order.The flow: provision a wallet with a public key, quote and order as usual, then sign the approvalMessage from GET /ramp/order/{orderId}/approvals and submit it to POST /ramp/order/{orderId}/approvals. Reserve, trustline, and gas costs are folded into the onramp fee shown in the quote. See the embedded wallets guide and the sandbox playground for the full walkthrough.

SPEI tracking code on orders

The order response and order_updated webhook now include a trackingCode field with the SPEI clave de rastreo for the fiat transfer. On onramps this is the incoming deposit key; on offramps, the outgoing payout key. Use it to look up the CEP receipt for reconciliation. The field appears once the SPEI transfer settles. See GET /ramp/order/{orderId}.

KYB via JWT launch flow

Partners can now launch users directly into KYB using target: /kyb in the JWT launch flow. The hosted KYB renders in a light, partner-friendly shell and shares the same compliance form as the main dashboard.

Standard `jti` claim for JWT replay protection

Partner JWTs now accept the standard jti (JWT ID, RFC 7519) claim for replay protection alongside the existing nonce claim. Use either one, or both (values must match). Existing integrations using nonce are unaffected. See the JWT authentication guide.

Verification-complete webhook

The bank_account_updated webhook now fires when biometric verification completes and the bank becomes compliant: true, so partners can react immediately without polling. Combined with the existing signal when a bank needs verification (compliant: false), the webhook now covers the full verification lifecycle.

Larger KYC document uploads

POST /ramp/customer/{customerId}/kyc/documents now accepts up to 10 MB per request (total across all images), up from the previous default. See the KYC docs endpoint for document requirements.

NewImproved

Partner JWT face-scan verification

Partners can now launch users straight into biometric face-scan verification using target: /idv in the JWT launch flow. MXN ramps require biometric verification before fiat transfers are enabled.

Agreement signing via launch flow

Launch users directly into electronic-signature and terms-and-conditions agreement flows using target: /agreements in the user launch flow. Works with both Firebase and partner JWT authentication.

Auth token access and refresh pairs

POST /auth/token now returns an access token and a refresh token. Use the refresh token to obtain a new access token without re-signing a JWT:

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<token>"
}

This builds on last week’s auth token endpoint; the JWT authentication guide covers the full flow.

PT wrap and unwrap orders on Solana

Partners can now execute Principal Token wrap and unwrap orders on Solana using the existing /ramp/quote and /ramp/swap flow with PT asset identifiers — the testing swaps guide walks through it.

KYC submission validates required fields

POST /ramp/customer/{customer_id}/kyc now validates required personal fields up front — email, phoneNumber, occupation, name, dateOfBirth, and a full address. Mexican customers (address.country: "MX") must include a CURP; an RFC is optional. Missing or invalid fields return 400 with a list of what to fix, as detailed in the onboarding guide.

Authentication errors link to docs

Errors from POST /auth/token and the JWT launch flow now include an error_uri (OAuth 2.0) that points to the matching entry in the authentication errors guide, so you can jump straight to the cause and fix.

NewImproved

Auth token endpoint

The new POST /auth/token endpoint issues access tokens for server-to-server calls — prefer it over launch-flow JWTs when you need backend-only access, as described in the JWT authentication guide.

Scoped API key enforcement

API keys now enforce scope-based access control: keys created after June 8 default to minimal scopes, while existing keys keep working unchanged. The authentication reference explains the scope model.

Bank compliance webhook signal

The bank_account_updated webhook now signals when a bank needs additional verification: while compliant is false, the bank can’t be used until the customer completes the verification flow.

Biometric verification

Identity verification now supports biometric face-scan — the foundation for the partner JWT launch flow.

Partner JWT auth launch

The partner dashboard can now launch users via partner-issued JWTs, so you can authenticate users with your own identity provider, as set up in the JWT authentication guide.

NewImproved

JWKS-based JWT verification

Partners can now register a JWKS endpoint for JWT-based authentication: the platform fetches and caches public keys from your /.well-known/jwks.json endpoint to verify partner-issued tokens, as described in the JWT authentication guide.

PT token metadata improvements

The partner dashboard now shows token metadata for all rampable assets, not just those currently held, improving asset selection when initiating quotes.

Improved

Better KYB error messages

KYB validation errors now return structured, field-level messages instead of generic failures, so partners get clearer guidance when a submission is incomplete or invalid.

NewImproved

Self-service API keys

Approved organizations can now generate their own API keys directly in the dashboard — no more requesting access over Slack. Once your organization is approved through KYB, create keys from your account settings; the authentication reference covers usage. In sandbox, organizations created through the portal are auto-approved, so you can generate keys and run the full flow immediately, as noted in the test environment guide.

KYB questionnaire renderer

KYB questionnaires now render dynamically based on organization type and jurisdiction, replacing the previous static form layout.

NewImproved

Client portal document upload

Customers can now upload KYB-required documents directly through the client portal during onboarding, removing manual document collection outside the platform.

Onboarding requirement progress

The onboarding flow now shows requirement-completion progress, so customers see exactly which steps remain before their organization is approved.

Entity editing and tax ID population

Organization entity details and tax identification numbers can now be edited after initial submission, so customers can correct mistakes without re-creating the organization.

​ Breaking: Bank accounts require an approved organization

​ KYC status is now a single 5-state value

​ Principal Tokens supported on all chains

​ /idv accepts addresses without postal codes

​ /idv marks email verified earlier

​ One onboarding flow: create org, launch /idv

​ Deprecated

​ MEXe fiat ramps on Base and EVM chains

​ Canonical asset metadata on GET /ramp/assets

​ USTRY, EUROB, and KTB now available for swaps

​ Restricted-country lookup endpoint

​ KYB legal name separate from organization display name

​ Swap USDC to and from MEXe on Solana

​ Self-serve JWT auth configuration

​ KYB partner API

​ Business identity verification via /idv

​ IDV Spanish localization

​ Embedded wallets

​ SPEI tracking code on orders

​ KYB via JWT launch flow

​ Standard jti claim for JWT replay protection

​ Verification-complete webhook

​ Larger KYC document uploads

​ Partner JWT face-scan verification

​ Agreement signing via launch flow

​ Auth token access and refresh pairs

​ PT wrap and unwrap orders on Solana

​ KYC submission validates required fields

​ Authentication errors link to docs

​ Auth token endpoint

​ Scoped API key enforcement

​ Bank compliance webhook signal

​ Biometric verification

​ Partner JWT auth launch

​ JWKS-based JWT verification

​ PT token metadata improvements

​ Better KYB error messages

​ Self-service API keys

​ KYB questionnaire renderer

​ Client portal document upload

​ Onboarding requirement progress

​ Entity editing and tax ID population

Breaking: Bank accounts require an approved organization

KYC status is now a single 5-state value

Principal Tokens supported on all chains

`/idv` accepts addresses without postal codes

`/idv` marks email verified earlier

One onboarding flow: create org, launch `/idv`

Deprecated

MEXe fiat ramps on Base and EVM chains

Canonical asset metadata on GET /ramp/assets

USTRY, EUROB, and KTB now available for swaps

Restricted-country lookup endpoint

KYB legal name separate from organization display name

Swap USDC to and from MEXe on Solana

Self-serve JWT auth configuration

KYB partner API

Business identity verification via /idv

IDV Spanish localization

Embedded wallets

SPEI tracking code on orders

KYB via JWT launch flow

Standard `jti` claim for JWT replay protection

Verification-complete webhook

Larger KYC document uploads

Partner JWT face-scan verification

Agreement signing via launch flow

Auth token access and refresh pairs

PT wrap and unwrap orders on Solana

KYC submission validates required fields

Authentication errors link to docs

Auth token endpoint

Scoped API key enforcement

Bank compliance webhook signal

Biometric verification

Partner JWT auth launch

JWKS-based JWT verification

PT token metadata improvements

Better KYB error messages

Self-service API keys

KYB questionnaire renderer

Client portal document upload

Onboarding requirement progress

Entity editing and tax ID population