Generate onboarding URL

curl --request POST \
  --url https://api.sand.etherfuse.com/ramp/onboarding-url \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "bankAccountId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "blockchain": "stellar",
  "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "publicKey": "GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL",
  "userInfo": {
    "displayName": "Ana García",
    "email": "[email protected]"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    bankAccountId: 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
    blockchain: 'stellar',
    customerId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    publicKey: 'GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL',
    userInfo: {displayName: 'Ana García', email: '[email protected]'}
  })
};

fetch('https://api.sand.etherfuse.com/ramp/onboarding-url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sand.etherfuse.com/ramp/onboarding-url"

payload = {
    "bankAccountId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "blockchain": "stellar",
    "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "publicKey": "GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL",
    "userInfo": {
        "displayName": "Ana García",
        "email": "[email protected]"
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "presigned_url": "https://api.sand.etherfuse.com/onboarding?org_id=a1b2c3d4-...&customer_id=a1b2c3d4-...&expires=1748345400&signature=..."
}

"You have already added user with this address, see org: b45a5a15-3e4b-4e92-9167-635dd7e95252"

Onboarding

Generate onboarding URL

Generates a presigned URL for customer onboarding. If the customer does not exist, it will be created. This is the primary endpoint for creating customers: you generate a UUID for customerId and bankAccountId, and Etherfuse creates the customer and bank account records associated with your organization.

Upon visiting the URL, the customer has 15 minutes to complete onboarding (KYC verification and bank account linking).

Personal organizations only

This endpoint always creates a personal organization — it forces individual KYC. There is no accountType field; pass business orgs through POST /ramp/organization instead.

userInfo

Pass userInfo with the end user’s email and display name. When provided, Etherfuse pre-creates the user record so the customer’s eventual sign-in attaches to the right user and we can email them on status changes (KYC approved/rejected, bank account verified, etc.). userInfo is currently optional but will become required in a future release — start sending it now.

Authenticating as the customer

If the customer signs in with a JWT (see JWT User Authentication), use the same value for customerId as the JWT sub. The shared id links the customer record to the user who signs in.

POST

ramp

onboarding-url

Generate onboarding URL

curl --request POST \
  --url https://api.sand.etherfuse.com/ramp/onboarding-url \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "bankAccountId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "blockchain": "stellar",
  "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "publicKey": "GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL",
  "userInfo": {
    "displayName": "Ana García",
    "email": "[email protected]"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    bankAccountId: 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
    blockchain: 'stellar',
    customerId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    publicKey: 'GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL',
    userInfo: {displayName: 'Ana García', email: '[email protected]'}
  })
};

fetch('https://api.sand.etherfuse.com/ramp/onboarding-url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sand.etherfuse.com/ramp/onboarding-url"

payload = {
    "bankAccountId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "blockchain": "stellar",
    "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "publicKey": "GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL",
    "userInfo": {
        "displayName": "Ana García",
        "email": "[email protected]"
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "presigned_url": "https://api.sand.etherfuse.com/onboarding?org_id=a1b2c3d4-...&customer_id=a1b2c3d4-...&expires=1748345400&signature=..."
}

"You have already added user with this address, see org: b45a5a15-3e4b-4e92-9167-635dd7e95252"

Authorizations

Authorization

string

header

required

API key sent in the Authorization header.

Body

application/json

bankAccountId

string<uuid>

required

blockchain

enum<string>

required

Canonical blockchain enum for API serialization. Use this type for JSON APIs and WebSocket messages. For database storage, convert to BlockchainType.

Available options:

stellar,

solana,

base,

polygon,

monad

customerId

string<uuid>

required

publicKey

string

required

uiOverride

string | null

userInfo

null | object

Optional info about the end user. Recommended — enables personalized status emails and links the user record to their Firebase identity. The hosted onboarding flow always creates a personal organization.

Show child attributes

Response

A presigned onboarding URL

List assets Get onboarding bank accounts

⌘I

User Authentication

Ramp API

Lookup API

Generate onboarding URL

Personal organizations only

userInfo

Authenticating as the customer

Authorizations

Body

Response