Create a Wallet

This recipe walks through the full wallet flow on Celar: create a wallet, inspect it, review balances and history, and deactivate it when it is no longer needed.

Examples use the sandbox environment. For production, replace api.sandbox.celar.io with api.celar.io.

How it works

1. Decide whether you need an organization wallet or a customer wallet
2. Create the wallet on a starting chain
3. List wallets under your PSP account
4. Fetch a wallet directly by wallet ID
5. Fetch a customer wallet by customer_id
6. Review aggregate balances and wallet history
7. Deactivate the wallet if it should stop receiving or sending funds

Before you start

• Use an API key with wallet permissions
• If you are creating a customer wallet, have a valid customer_id ready
• Choose the wallet's starting chain

Wallet types

Celar supports two wallet types under the PSP model:

Organization wallet

An organization wallet belongs to your PSP and is not tied to a specific customer. Use it for treasury balances, settlement flows, operational balances, or platform-owned funds.

Customer wallet

A customer wallet belongs to one end customer and is created by including a customer_id. Use it when funds should be associated with a specific customer.

info

Celar wallets are multichain by design. The chain you set at creation time is the starting deployment context, not a permanent chain restriction.

Step 1: Create the wallet

If you include a customer_id, Celar creates a customer wallet. If you omit it, Celar creates an organization wallet for your PSP.

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

Field	Required	Description
preferredName	Yes	Human-readable wallet name
chain	Yes	polygon, base, arbitrum, or another supported chain
customer_id	No	Provide a customer ID to create a customer wallet. Omit it to create an organization wallet.

Response

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

Step 2: List all wallets

Use this to verify the wallet exists and to inspect every wallet currently owned by your organization.

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

Step 3: Get one wallet by ID

After creation, save the returned wallet ID. Use it whenever you need the canonical wallet record.

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

Step 4: Get a wallet by customer

If the wallet was created for a customer, you can fetch it directly by customer_id.

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

Step 5: Check total balances

Use the total balances endpoint to get aggregated balances across all wallets owned by your organization.

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

Step 6: Review wallet transaction history

Fetch the transaction history for a specific wallet. This is useful for reconciliation and troubleshooting.

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

You can paginate the history response with limit and page.

Step 7: Deactivate the wallet

Deactivate the wallet when it should no longer send or receive funds.

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

warning

Once a wallet is deactivated, it cannot be reactivated.

What to use next

• Use Register a Customer before creating a customer wallet
• Use Payin or Fiat Payin once you are ready to receive funds