Wallets

Create Wallet

Create a new wallet with secure key custody.

curl -X POST \
  -H "x-api-key: dev-api-key" \
  -H "Content-Type: application/json" \
  -d '{"label": "trading-bot-1"}' \
  http://localhost:3000/api/v1/wallets

const response = await client.wallet.create({
  label: 'trading-bot-1'
});

response = requests.post(
    'http://localhost:3000/api/v1/wallets',
    headers={'x-api-key': 'dev-api-key'},
    json={'label': 'trading-bot-1'}
)

Request Body

string

Human-readable label for the wallet (1-128 characters)

boolean

default:false

Automatically fund with devnet SOL (devnet only)

number

Amount to fund in lamports when autoFund is true (max: 10,000,000,000)

Response

string

required

Unique wallet identifier (UUID)

string

required

Base58-encoded Solana public key

enum

required

Signer backend: local-dev, local-memory, kms, hsm, mpc

enum

required

Wallet status: active or disabled

string

Wallet label

string

required

ISO 8601 timestamp

object

Key custody information

Show properties

enum

encrypted-file, memory, kms, hsm, mpc

enum

local or external

boolean

Whether key derivation is deterministic

Example Response

{
  "status": "success",
  "stage": "completed",
  "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "publicKey": "7xKLvUhXW9XqHZzN3Jw8wVHGK6R4tN2gqV9mP3kL5eXy",
    "provider": "local-dev",
    "status": "active",
    "label": "trading-bot-1",
    "createdAt": "2026-03-08T12:00:00.000Z",
    "keyProvenance": {
      "backend": "encrypted-file",
      "custody": "local",
      "deterministicAddressing": false
    }
  }
}

Get Wallet

Retrieve wallet details by ID.

cURL

curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/wallets/550e8400-e29b-41d4-a716-446655440000

Path Parameters

string

required

Wallet UUID

Response

Returns the same structure as Create Wallet.

List Wallets

List all wallets for the current tenant.

cURL

curl -H "x-api-key: dev-api-key" \
     "http://localhost:3000/api/v1/wallets?limit=20&offset=0"

Query Parameters

number

default:"50"

Maximum number of wallets to return (max: 100)

number

default:"0"

Number of wallets to skip

Response

{
  "status": "success",
  "stage": "completed",
  "traceId": "...",
  "data": {
    "wallets": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "publicKey": "7xKLvUhXW9XqHZzN3Jw8wVHGK6R4tN2gqV9mP3kL5eXy",
        "provider": "local-dev",
        "status": "active",
        "label": "trading-bot-1",
        "createdAt": "2026-03-08T12:00:00.000Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

Get Balance

Retrieve SOL balance for a wallet.

cURL

curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/wallets/550e8400-e29b-41d4-a716-446655440000/balance

Path Parameters

string

required

Wallet UUID

Response

number

required

Balance in lamports (1 SOL = 1,000,000,000 lamports)

number

required

Balance in SOL (decimal)

{
  "status": "success",
  "stage": "completed",
  "traceId": "...",
  "data": {
    "lamports": 1000000000,
    "sol": 1.0
  }
}

Get Tokens

List all SPL token balances for a wallet.

cURL

curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/wallets/550e8400-e29b-41d4-a716-446655440000/tokens

Path Parameters

string

required

Wallet UUID

Response

array

required

Array of token balances

Show Token Object

string

required

Token mint address (base58)

string

required

Token amount (as string to preserve precision)

number

required

Token decimals

number

Human-readable amount (with decimals applied)

string

Associated token account address

{
  "status": "success",
  "stage": "completed",
  "traceId": "...",
  "data": {
    "tokens": [
      {
        "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "amount": "1000000",
        "decimals": 6,
        "uiAmount": 1.0,
        "tokenAccount": "3pXZ..."
      }
    ]
  }
}

Sign Message

Sign a message or transaction with the wallet’s private key.

curl -X POST \
  -H "x-api-key: dev-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA..."
  }' \
  http://localhost:3000/api/v1/wallets/550e8400-e29b-41d4-a716-446655440000/sign

curl -X POST \
  -H "x-api-key: dev-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "SGVsbG8gV29ybGQ="
  }' \
  http://localhost:3000/api/v1/wallets/550e8400-e29b-41d4-a716-446655440000/sign

Path Parameters

string

required

Wallet UUID

Request Body

string

Base64-encoded transaction (mutually exclusive with message)

string

Base64-encoded message (mutually exclusive with transaction)

Provide exactly one of transaction or message.

Response

string

required

Base64-encoded signature

string

required

Base58-encoded public key used for signing

{
  "status": "success",
  "stage": "completed",
  "traceId": "...",
  "data": {
    "signature": "3kZ8...",
    "publicKey": "7xKLvUhXW9XqHZzN3Jw8wVHGK6R4tN2gqV9mP3kL5eXy"
  }
}

Signer Backends

The wallet service supports multiple signer backends configured via environment variables:

Encrypted File
Memory
KMS
HSM
MPC

Best for: Local development and prototyping

WALLET_SIGNER_BACKEND=encrypted-file
WALLET_KEY_ENCRYPTION_SECRET=your-secret-key

Keys are encrypted at rest using AES-256-GCM.

Best for: Testing (non-persistent)

WALLET_SIGNER_BACKEND=memory

Keys are stored in memory only and lost on restart.

Best for: Managed key governance and auditing

WALLET_SIGNER_BACKEND=kms
WALLET_KMS_MASTER_SECRET=your-kms-master-secret
WALLET_KMS_KEY_ID=optional-key-id

Integrates with key management services.

Best for: Hardware-rooted custody and compliance

WALLET_SIGNER_BACKEND=hsm
WALLET_HSM_PIN=your-hsm-pin
WALLET_HSM_MODULE_SECRET=your-module-secret
WALLET_HSM_SLOT=optional-slot-number

Uses hardware security modules for signing.

Best for: Distributed custody and threshold signing

WALLET_SIGNER_BACKEND=mpc
WALLET_MPC_NODE_SECRETS=secret1,secret2,secret3
# OR
WALLET_MPC_NODE1_SECRET=secret1
WALLET_MPC_NODE2_SECRET=secret2
WALLET_MPC_NODE3_SECRET=secret3

Splits key material across multiple nodes.

Security Considerations

Private keys are never exposed via the API. All signing happens within the wallet engine boundary.

Use labels to identify wallets instead of storing public keys in your application.

Best Practices:

Use appropriate signer backend for your security requirements
Enable auto-fund only on devnet for testing
Implement wallet balance monitoring
Track wallet usage via audit events
Regularly rotate encryption secrets for encrypted-file backend
Use HSM or MPC backends for production custody

Overview

Endpoints

Create Wallet

Request Body

Response

Example Response

Get Wallet

Path Parameters

Response

List Wallets

Query Parameters

Response

Get Balance

Path Parameters

Response

Get Tokens

Path Parameters

Response

Sign Message

Path Parameters

Request Body

Response

Signer Backends

Security Considerations

​Create Wallet

​Request Body

​Response

​Example Response

​Get Wallet

​Path Parameters

​Response

​List Wallets

​Query Parameters

​Response

​Get Balance

​Path Parameters

​Response

​Get Tokens

​Path Parameters

​Response

​Sign Message

​Path Parameters

​Request Body

​Response

​Signer Backends

​Security Considerations

Create Wallet

Request Body

Response

Example Response

Get Wallet

Path Parameters

Response

List Wallets

Query Parameters

Response

Get Balance

Path Parameters

Response

Get Tokens

Path Parameters

Response

Sign Message

Path Parameters

Request Body

Response

Signer Backends

Security Considerations