Quickstart | Phoenix Wallet

This guide walks you through creating a wallet, crediting it with funds, and checking the balance.

Before You Begin

Make sure you have:

Your API credentials (client ID and secret)
An access token (see Authentication)

All examples assume you have set your access token in the ACCESS_TOKEN environment variable.

Step 1: Create a Wallet

First, create a wallet for your user:

curl -X POST https://api.phoenixwallet.io/v1/wallets \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user-12345",
    "name": "John Doe Wallet",
    "metadata": {
      "user_email": "john@example.com"
    }
  }'

const response = await fetch('https://api.phoenixwallet.io/v1/wallets', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    external_id: 'user-12345',
    name: 'John Doe Wallet',
    metadata: {
      user_email: 'john@example.com',
    },
  }),
});

const wallet = await response.json();
console.log('Created wallet:', wallet.id);

import os
import requests

response = requests.post(
    'https://api.phoenixwallet.io/v1/wallets',
    headers={
        'Authorization': f'Bearer {os.environ["ACCESS_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
        'external_id': 'user-12345',
        'name': 'John Doe Wallet',
        'metadata': {
            'user_email': 'john@example.com',
        },
    },
)

wallet = response.json()
print(f'Created wallet: {wallet["id"]}')

Response:

{
  "id": "wal_abc123",
  "external_id": "user-12345",
  "name": "John Doe Wallet",
  "status": "active",
  "metadata": {
    "user_email": "john@example.com"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

Step 2: Credit the Wallet

Add funds to the wallet by creating a credit operation:

curl -X POST https://api.phoenixwallet.io/v1/wallets/wal_abc123/credit \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_code": "USD",
    "amount": "100.00",
    "reference": "initial-deposit",
    "lot": {
      "attributes": {
        "source": "signup_bonus"
      }
    }
  }'

const walletId = 'wal_abc123';

const response = await fetch(
  `https://api.phoenixwallet.io/v1/wallets/${walletId}/credit`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      asset_code: 'USD',
      amount: '100.00',
      reference: 'initial-deposit',
      lot: {
        attributes: {
          source: 'signup_bonus',
        },
      },
    }),
  }
);

const credit = await response.json();
console.log('Credit operation:', credit.id);

import os
import requests

wallet_id = 'wal_abc123'

response = requests.post(
    f'https://api.phoenixwallet.io/v1/wallets/{wallet_id}/credit',
    headers={
        'Authorization': f'Bearer {os.environ["ACCESS_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
        'asset_code': 'USD',
        'amount': '100.00',
        'reference': 'initial-deposit',
        'lot': {
            'attributes': {
                'source': 'signup_bonus',
            },
        },
    },
)

credit = response.json()
print(f'Credit operation: {credit["id"]}')

Response:

{
  "id": "op_xyz789",
  "type": "credit",
  "wallet_id": "wal_abc123",
  "asset_code": "USD",
  "amount": "100.00",
  "reference": "initial-deposit",
  "lot_id": "lot_def456",
  "created_at": "2024-01-15T10:31:00Z"
}

Step 3: Check the Balance

Retrieve the wallet balance to confirm the credit:

curl https://api.phoenixwallet.io/v1/wallets/wal_abc123/balances \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const walletId = 'wal_abc123';

const response = await fetch(
  `https://api.phoenixwallet.io/v1/wallets/${walletId}/balances`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
    },
  }
);

const balances = await response.json();
console.log('Balances:', balances);

import os
import requests

wallet_id = 'wal_abc123'

response = requests.get(
    f'https://api.phoenixwallet.io/v1/wallets/{wallet_id}/balances',
    headers={
        'Authorization': f'Bearer {os.environ["ACCESS_TOKEN"]}',
    },
)

balances = response.json()
print(f'Balances: {balances}')

Response:

{
  "wallet_id": "wal_abc123",
  "balances": [
    {
      "asset_code": "USD",
      "available": "100.00",
      "reserved": "0.00",
      "total": "100.00"
    }
  ]
}

Next Steps

Now that you have created a wallet and added funds, you can:

Transfer funds between wallets
Create reservations to hold funds
Set up policies to control how funds are used
Explore the API Reference for all available operations