How to get a deposit address for a Customer

Overview

Customer purse address API allows you to get a reusable deposit address for a customer and a selected currency.

Use this guide after creating a customer. The returned purse address can be used for crypto deposits.

Integration flow

1. Create a customer and save the returned customer id.
2. Get a customer purse address by using the method - [POST] customer-purse/address/get
3. Save the returned purse id, address, and available currencies in your system.
4. Optionally get all customer purses by using the method - [POST] customer-purse/purse/get-all

Sequence

Names of requests on the scheme indicate Customer Purse API methods.

API methods

Get customer purse address - [POST] customer-purse/address/get

Request fields

Field	Type	Required	Description
account	string	Yes	Merchant account ID. The request will be sent for this account.
timestamp	number	Yes	Current Unix UTC timestamp in milliseconds. The value must not be less than 3 minutes in the past or greater than 3 minutes in the future.
payload	object	Yes	Object with customer ID and currency.

Payload fields

Field	Type	Required	Description
customerId	string	Yes	Calypso customer ID.
currency	string	Yes	Currency ticker used to request a purse address.

Request example

{
  "account": "0x0000000000000000000000000000000000000000",
  "timestamp": 1761650432438,
  "payload": {
    "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "currency": "USDT_TRX"
  }
}

Response fields

Field	Type	Description
id	string	Customer purse ID.
address	string	Customer deposit address.
currencies	array	Currencies available for this purse address.
createdDate	string	Date and time when the purse was created.

Response example 200 OK

{
  "id": "52bc94ac-7bac-49f0-a476-ac64c6634381",
  "address": "0x8ab54579efb614b9c46fb36db6a753df2cd18d65",
  "currencies": [
    "USDT_TRX"
  ],
  "createdDate": "2026-06-29T09:00:00.000Z"
}

Get customer purses - [POST] customer-purse/purse/get-all

Field	Type	Required	Description
customerId	string	Yes	Calypso customer ID.

The response contains the purses array. Each purse object contains id, address, currencies, and createdDate.

Address lifecycle

Case	Description
Address is generated	The customer can use the address for supported currency deposits.
Address has no deposits	If the address has not been funded for 30 days, it expires and Calypso sends CUSTOMER_PURSE_EXPIRED.
Address receives a confirmed deposit	The address lifetime is extended for another 12 months from the last confirmed incoming deposit.
Address expires	The merchant receives CUSTOMER_PURSE_EXPIRED and should request a new address if the customer needs to continue depositing.

Related docs

Document	Link
Create customer	How to create a Customer
Process customer transactions	How to process Customer transactions
Customers webhooks	Customers webhooks
Customer Purse API reference	Customer Purse API