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

Request Body

label

string

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

autoFund

boolean

default:false

Automatically fund with devnet SOL (devnet only)

fundLamports

number

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

Response

string

required

Unique wallet identifier (UUID)

publicKey

string

required

Base58-encoded Solana public key

provider

enum

required

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

status

enum

required

Wallet status: active or disabled

label

string

Wallet label

createdAt

string

required

ISO 8601 timestamp

keyProvenance

object

Key custody information

Show properties

backend

enum

encrypted-file, memory, kms, hsm, mpc

custody

enum

local or external

deterministicAddressing

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

walletId

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

limit

number

default:"50"

Maximum number of wallets to return (max: 100)

offset

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

walletId

string

required

Wallet UUID

Response

lamports

number

required

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

sol

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

walletId

string

required

Wallet UUID

Response

tokens

array

required

Array of token balances

Show Token Object

mint

string

required

Token mint address (base58)

amount

string

required

Token amount (as string to preserve precision)

decimals

number

required

Token decimals

uiAmount

number

Human-readable amount (with decimals applied)

tokenAccount

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

Path Parameters

walletId

string

required

Wallet UUID

Request Body

transaction

string

Base64-encoded transaction (mutually exclusive with message)

message

string

Base64-encoded message (mutually exclusive with transaction)

Provide exactly one of transaction or message.

Response

signature

string

required

Base64-encoded signature

publicKey

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

Build docs developers (and LLMs) love

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

Build docs developers (and LLMs) love

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