API Reference | Phoenix Wallet

The Phoenix Wallet API is organized around REST. All requests and responses use JSON.

Base URL

https://api.wallet.phoenixverse.io

Authentication

All endpoints require authentication via Bearer token:

Authorization: Bearer {{YOUR_TOKEN}}

See Authentication for details on obtaining and managing API tokens.

Idempotency

All mutating endpoints (POST, PUT, DELETE) require an Idempotency-Key header to ensure safe retries:

Idempotency-Key: {{UNIQUE_ID}}

Use a unique identifier (such as a UUID) for each distinct operation. Repeated requests with the same idempotency key will return the original response.

Request Format

All requests should include the following headers:

curl -X POST {{BASE_URL}}/wallets \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {{UNIQUE_ID}}" \
  -d '{
    "external_id": "user_12345",
    "metadata": {
      "user_name": "John Doe"
    }
  }'

Response Format

Success Response

{
  "data": {
    "id": "wal_abc123",
    "external_id": "user_12345",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "external_id",
        "message": "external_id is required"
      }
    ]
  }
}

Common HTTP Status Codes

Status	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing token
`404`	Not Found - Resource does not exist
`409`	Conflict - Idempotency key reused with different parameters
`422`	Unprocessable Entity - Business rule violation
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Endpoints

Resource	Description
Wallets	Create and manage wallets
Credits	Add funds to wallets
Transfers	Move funds between wallets
Reservations	Hold and release funds
Lots	Query and manage lots
Events	Stream ledger events

Pagination

List endpoints support cursor-based pagination:

GET {{BASE_URL}}/wallets?limit=20&cursor={{CURSOR}}

Parameter	Type	Description
`limit`	integer	Number of items per page (default: 20, max: 100)
`cursor`	string	Cursor for the next page of results

Paginated responses include:

{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6IndhbF9hYmMxMjMifQ=="
  }
}