API Reference

API Reference

WAIaaS exposes a REST API on http://127.0.0.1:3100. All endpoints are defined using OpenAPI 3.0 decorators and the daemon serves the full specification at runtime.

Note: This document provides an overview of authentication, endpoint categories, and error codes. For complete request/response schemas, parameter details, and examples, use the OpenAPI specification served by the daemon.

Base URL

http://127.0.0.1:3100

The daemon binds to 127.0.0.1 (localhost only) by default. Do not expose it directly to the public internet.

Authentication

WAIaaS uses three authentication methods, each scoped to a different actor:

masterAuth (System Administrator)

Header: X-Master-Password: <your-master-password>

Used for system administration: creating wallets, managing sessions, configuring policies, Admin API operations. The master password is hashed with Argon2id.

curl -X POST http://127.0.0.1:3100/v1/wallets \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{"name": "my-wallet", "chain": "solana", "environment": "mainnet"}'

sessionAuth (AI Agent)

Header: Authorization: Bearer wai_sess_<jwt-token>

Used by AI agents and SDKs for wallet queries, transaction submission, and session-scoped operations. Session tokens are JWTs issued via POST /v1/sessions and scoped to a specific wallet.

curl http://127.0.0.1:3100/v1/wallet/balance \
  -H "Authorization: Bearer wai_sess_eyJhbGciOiJIUzI1NiJ9..."

ownerAuth (Fund Owner)

Headers: X-Owner-Signature: <signature> + X-Owner-Message: <message>

Used by the fund owner (human) for high-value transaction approval, kill switch recovery, and owner verification. Supports SIWS (Sign-In with Solana) and SIWE (Sign-In with Ethereum) signature schemes.

curl -X POST http://127.0.0.1:3100/v1/transactions/<tx-id>/approve \
  -H "X-Owner-Signature: <ed25519-or-secp256k1-signature>" \
  -H "X-Owner-Message: <signed-message>"

OpenAPI Specification

The daemon serves a complete OpenAPI 3.0 JSON specification at runtime:

# Download the spec
curl http://127.0.0.1:3100/doc -o openapi.json

# View interactive documentation
open http://127.0.0.1:3100/reference

The spec includes all request/response schemas, parameter definitions, and example payloads. All route definitions use @hono/zod-openapi decorators, which means the OpenAPI spec is always in sync with the actual implementation.

Endpoint Summary

System (Public)

Wallets (masterAuth)

Wallet (sessionAuth -- Session-Scoped)

Sessions (masterAuth / sessionAuth)

Transactions (sessionAuth / ownerAuth)

Transaction Types (discriminatedUnion by type field):

Policies (masterAuth)

Policy Types: SPENDING_LIMIT, WHITELIST, ALLOWED_TOKENS, CONTRACT_WHITELIST, APPROVED_SPENDERS, RATE_LIMIT, TIME_WINDOW, GAS_LIMIT, AUTOSTOP, X402_ALLOWED_DOMAINS, CUMULATIVE_SPENDING_LIMIT, DISPLAY_CURRENCY.

Tokens (masterAuth / sessionAuth)

Actions (sessionAuth)

x402 Payments (sessionAuth)

WalletConnect (masterAuth / sessionAuth)

MCP Token Provisioning (masterAuth)

Admin (masterAuth)

Error Codes

All errors follow a consistent JSON format:

{
  "error": {
    "code": "WALLET_NOT_FOUND",
    "message": "Wallet 'abc-123' not found",
    "domain": "WALLET",
    "retryable": false
  }
}

Common Error Codes

The daemon defines 83 error codes across 11 domains (AUTH, SESSION, TX, POLICY, OWNER, SYSTEM, WALLET, WITHDRAW, ACTION, ADMIN, X402). For the complete list, consult the OpenAPI specification at GET /doc.

SDKs

TypeScript SDK

npm install @waiaas/sdk

Zero external dependencies. Provides typed methods for all session-scoped endpoints.

import { WAIaaSClient } from '@waiaas/sdk';

const client = new WAIaaSClient({
  baseUrl: 'http://127.0.0.1:3100',
  sessionToken: 'wai_sess_...',
});

const balance = await client.getBalance();
const tx = await client.sendToken({ to: '...', amount: '0.5' });

See: @waiaas/sdk on npm

Python SDK

pip install waiaas

Built on httpx + Pydantic v2 with async/await support.

from waiaas import WAIaaSClient

async with WAIaaSClient("http://127.0.0.1:3100", "wai_sess_...") as client:
    balance = await client.get_balance()
    tx = await client.send_token("recipient...", "0.5")

See: python-sdk/README.md

MCP (Model Context Protocol)

The MCP server exposes WAIaaS as tools for AI agents (Claude, etc.):

waiaas mcp setup  # Automatic Claude Desktop configuration

Tools: send_token, get_balance, get_address, list_transactions, get_transaction, get_nonce, plus dynamic Action Provider tools.

Resources: waiaas://wallet/balance, waiaas://wallet/address, waiaas://system/status.

See: @waiaas/mcp on npm

Related

• Architecture - System architecture and pipeline overview
• Agent Self-Setup Guide - Using the API for automated setup
• Agent Skills Integration Guide - Teaching agents to use the API via skills