Creating External Accounts

Persist paired source and destination accounts so intents can route funds correctly.

External accounts represent the bank accounts or crypto addresses where funds will be sent or received. GnosisRamp creates external accounts in pairs — one source and one destination — to match a specific currency route.

First step: Retrieve the JSON Schema requirements by following the Fetching External Account Requirements guide. The schemas define the exact fields and validation rules for each account type.

Paired Creation

Once you have a GnosisRamp JWT and the requirement schemas, call POST /customers/external-accounts to register both the source and destination accounts in a single request. The customer ID is automatically extracted from the JWT — no need to include it in the URL.

The request body uses four fields:

• src — source currency code (e.g., USD)
• dest — destination currency code (e.g., USDC_GNO)
• source — metadata object conforming to the source JSON Schema from requirements
• destination — metadata object conforming to the destination JSON Schema from requirements

Example — USD to USDC on Gnosis

cURL

curl -X POST https://api.gnosisramp.io/v1/customers/external-accounts \
  -H "Authorization: Bearer $GNOSISRAMP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "src": "USD",
        "dest": "USDC_GNO",
        "source": {
          "rails": "ACH",
          "currency": "USD",
          "institutionName": "Chase Bank",
          "accountIdentifier": {
            "routingNumber": "021000021",
            "accountNumber": "123456789012"
          },
          "beneficiary": {
            "name": "Jane Doe",
            "taxId": "123-45-6789"
          }
        },
        "destination": {
          "address": "0x742d35Cc6634C0532925a3b84cF2f7c7f3B2f5f8",
          "currency": "USDC_GNO"
        }
      }'

Response

{
  "source": {
    "id": "ext_acc_src_123",
    "type": "BANK_ACCOUNT",
    "label": null,
    "metadata": { "rails": "ACH", "currency": "USD", "..." },
    "currencyId": "usd-currency-id",
    "currency": { "code": "USD", "ticker": "USD", "type": "FIAT", "decimals": 2, "..." },
    "createdAt": "2025-01-12T21:45:11.201Z",
    "updatedAt": "2025-01-12T21:45:11.201Z"
  },
  "destination": {
    "id": "ext_acc_dest_456",
    "type": "CRYPTO_ADDRESS",
    "label": null,
    "metadata": { "address": "0x742d35Cc...", "currency": "USDC_GNO" },
    "currencyId": "usdc-gno-currency-id",
    "currency": { "code": "USDC_GNO", "ticker": "USDC", "type": "CRYPTO", "decimals": 6, "..." },
    "createdAt": "2025-01-12T21:45:11.201Z",
    "updatedAt": "2025-01-12T21:45:11.201Z"
  }
}

Persist the returned source.id and destination.id — you will reference them as srcExternalAccountId and destExternalAccountId when creating intents.

Error handling

Status	Meaning	Fix
400 Bad Request	Schema validation failed (pattern mismatch, unsupported rail, etc.)	Re-run the requirements call and fix the payload.
401 Unauthorized	Missing/expired GnosisRamp JWT	Exchange the subject token again.

How External Accounts Drive Provider Selection

When you create an intent, GnosisRamp uses the external account metadata to determine which providers are eligible. Specifically:

External Account Field	Used For
currency.code	Must match a provider’s supported source/destination currencies
type (BANK_ACCOUNT, CRYPTO_ADDRESS)	Must match the provider’s expected account type
metadata.rail (ACH, WIRE, PIX, etc.)	Must be in the provider’s supported rails
metadata.countryCode	Must match the provider’s supported countries

This means the external account details you submit here are not just stored data — they actively filter which providers can handle the payment. If you later pass a providerId when creating the intent, it must be one of the providers that passed all these capability checks.

Best practices

• Always create accounts as pairs for a specific currency route — GnosisRamp needs both source and destination IDs on the intent.
• Validate your source and destination objects against the JSON Schemas from the requirements endpoint before submitting.
• Query supported currencies first to know which src/dest combinations are available.