Wallets | Phoenix Wallet

Wallets are the core resource in Phoenix Wallet. Each wallet can hold multiple asset types and maintains a complete transaction history.

Create Wallet

Create a new wallet for a user or entity.

POST /wallets

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	Yes	Unique request identifier

Request Body

Field	Type	Required	Description
`external_id`	string	Yes	Your unique identifier for this wallet
`metadata`	object	No	Custom key-value pairs for your reference
`policies`	array	No	Policy IDs to attach to this wallet

Example Request

curl -X POST {{BASE_URL}}/wallets \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {{IDEMPOTENCY_KEY}}" \
  -d '{
    "external_id": "user_12345",
    "metadata": {
      "user_name": "John Doe",
      "tier": "gold"
    },
    "policies": ["pol_default"]
  }'

Example Response

{
  "data": {
    "id": "wal_abc123def456",
    "external_id": "user_12345",
    "status": "active",
    "metadata": {
      "user_name": "John Doe",
      "tier": "gold"
    },
    "policies": ["pol_default"],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Error Codes

Code	Description
`DUPLICATE_EXTERNAL_ID`	A wallet with this external_id already exists
`INVALID_POLICY`	One or more policy IDs are invalid
`VALIDATION_ERROR`	Request body validation failed

Get Wallet

Retrieve a wallet by its ID.

GET /wallets/{{WALLET_ID}}

Path Parameters

Parameter	Type	Description
`wallet_id`	string	The wallet ID (e.g., `wal_abc123def456`)

Example Request

curl -X GET {{BASE_URL}}/wallets/{{WALLET_ID}} \
  -H "Authorization: Bearer {{API_KEY}}"

Example Response

{
  "data": {
    "id": "wal_abc123def456",
    "external_id": "user_12345",
    "status": "active",
    "metadata": {
      "user_name": "John Doe",
      "tier": "gold"
    },
    "policies": ["pol_default"],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T12:00:00Z"
  }
}

Error Codes

Code	Description
`WALLET_NOT_FOUND`	No wallet exists with this ID

Get Wallet by External ID

Retrieve a wallet using your external identifier.

GET /wallets/external/{{EXTERNAL_ID}}

Path Parameters

Parameter	Type	Description
`external_id`	string	Your external identifier for the wallet

Example Request

curl -X GET {{BASE_URL}}/wallets/external/user_12345 \
  -H "Authorization: Bearer {{API_KEY}}"

Example Response

Same as Get Wallet.

Get Wallet Balances

Retrieve all balances for a wallet, broken down by asset type.

GET /wallets/{{WALLET_ID}}/balances

Path Parameters

Parameter	Type	Description
`wallet_id`	string	The wallet ID

Query Parameters

Parameter	Type	Default	Description
`asset`	string	all	Filter by asset type
`include_reserved`	boolean	true	Include reserved amounts

Example Request

curl -X GET "{{BASE_URL}}/wallets/{{WALLET_ID}}/balances?include_reserved=true" \
  -H "Authorization: Bearer {{API_KEY}}"

Example Response

{
  "data": {
    "wallet_id": "wal_abc123def456",
    "balances": [
      {
        "asset": "POINTS",
        "available": "1500.00",
        "reserved": "200.00",
        "total": "1700.00"
      },
      {
        "asset": "BONUS",
        "available": "50.00",
        "reserved": "0.00",
        "total": "50.00"
      }
    ],
    "as_of": "2024-01-15T12:00:00Z"
  }
}

Update Wallet

Update wallet metadata or policies.

PATCH /wallets/{{WALLET_ID}}

Path Parameters

Parameter	Type	Description
`wallet_id`	string	The wallet ID

Request Body

Field	Type	Required	Description
`metadata`	object	No	Merge with existing metadata (set value to `null` to remove a key)
`policies`	array	No	Replace all attached policies
`status`	string	No	Set to `suspended` or `active`

Example Request

curl -X PATCH {{BASE_URL}}/wallets/{{WALLET_ID}} \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {{IDEMPOTENCY_KEY}}" \
  -d '{
    "metadata": {
      "tier": "platinum",
      "old_field": null
    },
    "status": "active"
  }'

Example Response

{
  "data": {
    "id": "wal_abc123def456",
    "external_id": "user_12345",
    "status": "active",
    "metadata": {
      "user_name": "John Doe",
      "tier": "platinum"
    },
    "policies": ["pol_default"],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T14:00:00Z"
  }
}

Error Codes

Code	Description
`WALLET_NOT_FOUND`	No wallet exists with this ID
`INVALID_STATUS_TRANSITION`	Cannot transition to the requested status
`INVALID_POLICY`	One or more policy IDs are invalid

List Wallets

Retrieve a paginated list of wallets.

GET /wallets

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Number of results (max 100)
`cursor`	string	-	Pagination cursor
`status`	string	-	Filter by status (`active`, `suspended`)
`external_id_prefix`	string	-	Filter by external ID prefix

Example Request

curl -X GET "{{BASE_URL}}/wallets?limit=10&status=active" \
  -H "Authorization: Bearer {{API_KEY}}"

Example Response

{
  "data": [
    {
      "id": "wal_abc123def456",
      "external_id": "user_12345",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T14:00:00Z"
    },
    {
      "id": "wal_def456ghi789",
      "external_id": "user_67890",
      "status": "active",
      "created_at": "2024-01-14T08:00:00Z",
      "updated_at": "2024-01-14T08:00:00Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6IndhbF9kZWY0NTZnaGk3ODkifQ=="
  }
}

Suspend Wallet

Suspend a wallet to prevent any transactions.

POST /wallets/{{WALLET_ID}}/suspend

Path Parameters

Parameter	Type	Description
`wallet_id`	string	The wallet ID

Request Body

Field	Type	Required	Description
`reason`	string	No	Reason for suspension

Example Request

curl -X POST {{BASE_URL}}/wallets/{{WALLET_ID}}/suspend \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {{IDEMPOTENCY_KEY}}" \
  -d '{
    "reason": "Fraud investigation"
  }'

Example Response

{
  "data": {
    "id": "wal_abc123def456",
    "external_id": "user_12345",
    "status": "suspended",
    "suspended_at": "2024-01-15T15:00:00Z",
    "suspension_reason": "Fraud investigation",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T15:00:00Z"
  }
}

Error Codes

Code	Description
`WALLET_NOT_FOUND`	No wallet exists with this ID
`WALLET_ALREADY_SUSPENDED`	Wallet is already suspended