Back to the reference

Wallets

On-chain USDT destinations.

Wallets receive USDT withdrawals. The POST /crypto-beneficiaries body uses camelCase (walletType, travelAddress). Chains: tron, eth or polygon. The only asset is USDT.

POST

Create a wallet

/api/v1/crypto-beneficiaries

Register a USDT destination. Scope payouts:write.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

name
body
stringRequired

Wallet holder name.

chain
body
stringRequired

Address chain.

tron · eth · polygon

asset
body
stringRequired

USDT only.

address
body
stringRequired

Destination address (TRON base58check or 0x… EVM).

walletType
body
stringOptional

Defaults to self_hosted.

self_hosted · institution

travelAddress
body
stringOptional

Travel Rule: ta… code, only if walletType is institution.

Responses

  • HTTP 201Wallet created. The address is stored encrypted: the response does not include it, only addressLast6 and addressMasked.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 422invalid_addressInvalid address or chain.
POST/crypto-beneficiaries
curl -X POST "$CLOBEPAY_API_BASE/crypto-beneficiaries" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY" \  -H "Content-Type: application/json" \  -d '{"name":"Atlas Creativo LLC","chain":"tron","asset":"USDT","address":"TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL","walletType":"self_hosted"}'

Response

HTTP 201
{
  "id": "a41c82e7-3b6d-4c90-9e2a-5f17d0b8c4e3",
  "name": "Atlas Creativo LLC",
  "chain": "tron",
  "asset": "USDT",
  "addressLast6": "1NYqeL",
  "addressMasked": "…1NYqeL",
  "walletType": "self_hosted"
}

GET

List wallets

/api/v1/crypto-beneficiaries

Wallets of your merchant. Scope payouts:read.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

Responses

  • HTTP 200List.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
GET/crypto-beneficiaries
curl -X GET "$CLOBEPAY_API_BASE/crypto-beneficiaries" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
{
  "items": []
}

GET

Retrieve a wallet

/api/v1/crypto-beneficiaries/{walletId}

Detail by UUID. Scope payouts:read.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

walletId
path
uuidRequired

Wallet UUID.

Responses

  • HTTP 200Detail (addressLast6 and addressMasked, without the full address).

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 404not_foundIt does not exist or is not yours. Also if walletId is not a UUID.
GET/crypto-beneficiaries/{walletId}
curl -X GET "$CLOBEPAY_API_BASE/crypto-beneficiaries/a41c82e7-3b6d-4c90-9e2a-5f17d0b8c4e3" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
Detail (addressLast6 and addressMasked, without the full address).