Customers

The Customers API lets you create managed accounts for your own customers. Each customer gets their own wallets and transaction history under your platform account — you keep full programmatic control while each customer’s data stays separate. This is the foundation of a wallet-as-a-service product: you use the Yativo API on your backend, and your customers use your interface.

These are wallet customers — not card customers. If you are issuing crypto cards, your cardholders are managed separately via the Card Issuer API. The two use different customer records and endpoints.

Type Definitions

interface Customer {
  _id: string;            // The customer ID used in every other customer endpoint
  username: string;
  email: string;
  phone_number: string;
  user_id: string;        // Your platform account
  createdAt: string;
  updatedAt: string;
}

interface CustomerListItem extends Customer {
  wallet_address: string | null;   // First wallet address, if any
  balance_usd: number;             // Total wallet balance in USD
}

interface CustomerDetails {
  customer: Customer;
  assets: CustomerWallet[];
  balance_usd: number;
  wallet_address: string | null;
  metrics: {
    total_volume: number;       // USD
    total_sent: number;         // USD
    total_received: number;     // USD
    first_active: string;
    last_active: string | null;
    transaction_count: number;
  };
}

Create a customer

POST /v1/customers/create-customer

string

required

Display name for the customer.

string

required

Customer email address. Must be unique.

curl -X POST 'https://crypto-api.yativo.com/api/v1/customers/create-customer' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "Acme Corp",
    "email": "billing@acme.com"
  }'

Response

{
  "status": true,
  "message": "Customer created successfully !",
  "data": {
    "_id": "6650a1f2c3d4e5f6a7b8c9d0",
    "username": "Acme Corp",
    "email": "billing@acme.com",
    "phone_number": "",
    "user_id": "664f0e1d2c3b4a5968778695",
    "createdAt": "2026-09-30T10:00:00.000Z",
    "updatedAt": "2026-09-30T10:00:00.000Z"
  }
}

A customer.created webhook is sent when the customer is created.

List customers

POST /v1/customers/get-customers

string

Matches username, email, or a wallet address.

number

default:"1"

Page number.

number

default:"20"

Results per page.

curl -X POST 'https://crypto-api.yativo.com/api/v1/customers/get-customers' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "search": "acme", "page": 1, "limit": 20 }'

Response

{
  "status": true,
  "message": "Customers listed successfully",
  "data": [
    {
      "_id": "6650a1f2c3d4e5f6a7b8c9d0",
      "username": "Acme Corp",
      "email": "billing@acme.com",
      "phone_number": "",
      "wallet_address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "balance_usd": 1250.4,
      "createdAt": "2026-09-30T10:00:00.000Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_records": 1,
    "records_per_page": 20
  }
}

Get a customer

Returns the customer’s profile, wallets, total balance and activity metrics.

GET /v1/customers/{customer_id}

curl 'https://crypto-api.yativo.com/api/v1/customers/6650a1f2c3d4e5f6a7b8c9d0' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response

{
  "status": true,
  "message": "Customer details retrieved successfully",
  "data": {
    "customer": {
      "_id": "6650a1f2c3d4e5f6a7b8c9d0",
      "username": "Acme Corp",
      "email": "billing@acme.com",
      "phone_number": ""
    },
    "assets": [ { "...": "..." } ],
    "balance_usd": 1250.4,
    "wallet_address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "metrics": {
      "total_volume": 8420.15,
      "total_sent": 3100,
      "total_received": 5320.15,
      "first_active": "2026-09-01T09:12:00.000Z",
      "last_active": "2026-09-29T18:40:00.000Z",
      "transaction_count": 42
    }
  }
}

Update a customer

PATCH /v1/customers/{customer_id}

Send only the fields you want to change.

string

Display name.

string

Email address.

string

Phone number.

curl -X PATCH 'https://crypto-api.yativo.com/api/v1/customers/6650a1f2c3d4e5f6a7b8c9d0' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "phone_number": "+14155550100" }'

Delete a customer

DELETE /v1/customers/{customer_id}

curl -X DELETE 'https://crypto-api.yativo.com/api/v1/customers/6650a1f2c3d4e5f6a7b8c9d0' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Move any remaining funds out of the customer’s wallets before deleting the customer.

Customer transactions

POST /v1/customers/get-customer-transactions

string

required

The customer ID.

number

default:"1"

Page number.

number

default:"50"

Results per page.

string

Filter by transaction type.

string

Filter by status.

string

Search text.

curl -X POST 'https://crypto-api.yativo.com/api/v1/customers/get-customer-transactions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "customer_id": "6650a1f2c3d4e5f6a7b8c9d0", "page": 1, "limit": 50 }'

Customer wallets

Add wallets to a customer with the Assets API:

# Add a wallet for a customer
curl -X POST 'https://crypto-api.yativo.com/api/v1/assets/add-customer-asset' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "6650a1f2c3d4e5f6a7b8c9d0",
    "ticker_name": "USDC_SOL"
  }'

# List a customer's wallets
curl -X POST 'https://crypto-api.yativo.com/api/v1/assets/get-customer-assets' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "customer_id": "6650a1f2c3d4e5f6a7b8c9d0" }'

Field	Required	Notes
`customer_id`	Yes	The customer ID.
`ticker_name` or `asset_id`	Yes	The asset to create a wallet for, e.g. `USDC_SOL`.
`allow_multiple`	No	By default, adding the same asset again returns the existing wallet. Set `true` to create another.

Auto-forward a customer’s deposits

Forward incoming deposits on a customer’s wallet to another address automatically, for example to sweep funds into your treasury.

Set the rule

POST /v1/customers/{customer_id}/auto-forward

string

required

Address to forward to.

string

required

The asset to forward.

string

required

The chain, e.g. SOL.

number

default:"100"

Share of each deposit to forward.

string

default:"0.0001"

Deposits below this aren’t forwarded.

boolean

default:"true"

Turn the rule on or off.

curl -X POST 'https://crypto-api.yativo.com/api/v1/customers/6650a1f2c3d4e5f6a7b8c9d0/auto-forward' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "destination_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "asset_id": "665a0b1c2d3e4f5a6b7c8d9e",
    "chain": "SOL",
    "percentage": 100
  }'

Calling it again for the same customer, asset and chain updates the existing rule.

Get the rule

GET /v1/customers/{customer_id}/auto-forward

Returns the rule, or null if the customer has none. For rules across many wallets, see Auto-Forwarding.

Sandbox

Use the same endpoints against https://crypto-sandbox.yativo.com/api/v1/ with a sandbox token. See Sandbox Overview.

Overview

Wallets & Assets

Transactions

Yativo Card

Payment Gateway

Agentic Wallets

Automation

Compliance

B2B

Developer Tools

Tutorials

Sandbox

Create a customer

List customers

Get a customer

Update a customer

Delete a customer

Customer transactions

Customer wallets

Auto-forward a customer’s deposits

Set the rule

Get the rule

Sandbox

​Create a customer

​List customers

​Get a customer

​Update a customer

​Delete a customer

​Customer transactions

​Customer wallets

​Auto-forward a customer’s deposits

​Set the rule

​Get the rule

​Sandbox

Create a customer

List customers

Get a customer

Update a customer

Delete a customer

Customer transactions

Customer wallets

Auto-forward a customer’s deposits

Set the rule

Get the rule

Sandbox