Wallets API Endpoints

Celar wallets are fully manageable through API calls.
Wallets are used across payment operations as sources, destinations, or fee recipients.

Depending on how a wallet is created, it can represent either:

• an organization wallet (PSP / Developer), or
• a customer wallet (owned by an end customer)

Celar wallets are multichain by design.
The blockchain specified during wallet creation defines the initial deployment context only and does not restrict the wallet to that chain.
Once created, the same wallet can be used across all supported blockchains.

1. Create a Wallet

Create a new Celar wallet.

If a customer_id is provided, the wallet is created as a customer wallet.
If customer_id is omitted, the wallet is created as an organization wallet.

The chain parameter specifies the starting chain for the wallet.
The wallet remains a single logical entity and can later be used on other supported chains (for example, a wallet created on Polygon can be used on Base or Arbitrum).

curl --request POST \
  --url https://api.sandbox.celar.io/api/v1/psps/wallets \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "preferredName": "celar1",
    "chain": "polygon",
    "customer_id": "cr_9b1a0afff50e88d8"
  }'

Parameters

Field	Type	Required	Description
preferredName	string	Yes	Human-readable wallet name
chain	string	Yes	Blockchain network
customer_id	string	No	Creates a customer wallet when provided

Example Response

{
  "message": "Wallet created successfully",
  "wallet": {
    "id": "cw_edf59f149ef0",
    "preferred_name": "celar1_polygon",
    "chain": "polygon",
    "address": "0xabAD28035be9DDB6703De46692cdE50cc786E8b7",
    "is_active": true,
    "created_at": "2025-09-26T14:59:58.999Z",
    "updated_at": "2025-09-26T14:59:58.999Z"
  }
}

2. Get All Wallets

List all wallets owned by the authenticated organization.

curl --request GET \
  --url https://api.sandbox.celar.io/api/v1/psps/wallets \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <api_key>'

3. Get One Wallet by ID

Retrieve a single wallet by its wallet ID.

curl --request GET \
  --url https://api.sandbox.celar.io/api/v1/psps/wallets/id/<wallet_id> \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <api_key>'

4. Get Wallet by Customer

Retrieve the wallet associated with a specific customer.

This endpoint is typically used by developers to fetch a customer’s wallet and balances.

curl --request GET \
  --url https://api.sandbox.celar.io/api/v1/psps/wallets/customers/cr_9b1a0afff50e88d8 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <api_key>'

5. Get Total Balances

Retrieve the aggregated balances across all wallets owned by the organization.

curl --request GET \
  --url https://api.sandbox.celar.io/api/v1/psps/wallets/total_balances \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <api_key>'

6. Get Wallet Transactions

Fetch the transaction history for a wallet.

Supports pagination using limit and page.

curl --request GET \
  --url https://api.sandbox.celar.io/api/v1/psps/wallets/history/<wallet_id> \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <api_key>'

7. Deactivate a Wallet

Deactivate a wallet so it can no longer send or receive funds.

⚠️ Once deactivated, a wallet cannot be reactivated.

curl --request DELETE \
  --url https://api.sandbox.celar.io/api/v1/psps/wallets/id/<wallet_id> \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <api_key>'