Self-Documenting Economic Agents: OpenAPI 3.0 for Autonomous Commerce

AI agents will need to pay for compute, data, and API calls — and the infrastructure to make that happen exists today, not in some speculative roadmap. If you're building agents that operate autonomously, you've probably already hit the wall: your agent can reason, plan, and act, but the moment it needs to move money, you're back to human-in-the-loop plumbing. This post is about closing that gap with real, working infrastructure.

The Problem No One Talks About at AI Conferences

There's a lot of conversation about reasoning capabilities, context windows, and tool use. Considerably less conversation about the boring but critical question: how does an agent pay for things?

Think through the lifecycle of an autonomous agent doing something genuinely useful — say, a research agent that monitors market conditions, queries premium data APIs, executes trades, and rebalances a portfolio overnight. Every one of those steps involves either a cost or a value transfer:

• Querying a premium data feed costs money (someone has to pay the API provider)
• Executing a swap on-chain requires gas
• Moving funds between protocols requires signing transactions
• Reporting results might involve paying for a delivery channel

Today, most teams handle this by giving the agent access to a human-controlled wallet with full permissions, or by hard-coding payment credentials that get rotated manually. Neither approach scales, and neither is safe. What's actually needed is wallet infrastructure designed for agents from the ground up — with policy enforcement, audit trails, and the kind of self-documentation that lets agents (and developers) discover capabilities at runtime.

Wallets That Speak HTTP

WAIaaS (Wallet-as-a-Service for AI agents) is an open-source, self-hosted daemon that treats wallet operations as a REST API. Instead of your agent importing a private key and calling a library directly, it makes HTTP calls to a local service that handles key management, transaction signing, policy enforcement, and multi-chain routing.

The architecture is deliberately simple: you run the daemon, create a wallet, issue a session token to your agent, and the agent operates within the boundaries you set. The daemon exposes 39 REST API route modules covering everything from balance queries to DeFi actions to NFT transfers.

What makes this relevant to the "autonomous commerce" question is the combination of two things: a machine-readable OpenAPI 3.0 spec and native x402 HTTP payment support. Together, they mean an agent can discover what a wallet service can do and automatically pay for API calls that require payment — without a human in the loop for either step.

OpenAPI as Agent Infrastructure

When WAIaaS is running, you get a self-documenting API at two endpoints:

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

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

The /doc endpoint returns a machine-readable OpenAPI 3.0 specification. The /reference endpoint serves an interactive Scalar UI for human exploration. This matters more than it might seem at first glance.

An OpenAPI spec is a contract. It describes every endpoint, every required parameter, every possible response code. For a human developer, that's useful documentation. For an agent — especially one using an LLM with tool-calling capabilities — it's a capability manifest that can be parsed, indexed, and acted on at runtime.

Consider what this enables: an orchestrator agent could fetch the spec from a WAIaaS instance, understand that the wallet supports token transfers, contract calls, DeFi actions across 15 integrated protocols, and NFT operations — then route sub-tasks to the appropriate endpoints without any hardcoded knowledge of the API surface. The agent discovers capabilities the same way a developer does, just programmatically.

The x402 Layer: Agents That Pay for What They Use

The x402 HTTP payment protocol is the piece that makes autonomous economic participation concrete. When an agent calls an API that returns HTTP 402 (Payment Required), the x402 protocol defines a standard handshake: the server declares what it wants, the client pays, the server fulfills the request.

WAIaaS has native x402 support built in. From the agent's perspective, this is just a fetch call:

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

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

The TypeScript SDK includes x402Fetch() — a drop-in replacement for standard HTTP fetch that automatically handles 402 responses by paying from the agent's wallet and retrying the request. The agent doesn't need to know whether a given API costs money; it just makes requests and the payment layer handles the rest.

This is the "machines that pay for what they use" model made operational. A premium data API, a compute provider, a specialized model endpoint — any service implementing x402 becomes something agents can consume autonomously, with payment flowing automatically and every transaction recorded in the wallet's audit trail.

To control which domains an agent can pay automatically, you configure the X402_ALLOWED_DOMAINS policy:

curl -X POST http://localhost:3100/v1/policies \
  -H 'Content-Type: application/json' \
  -H 'X-Master-Password: <password>' \
  -d '{
    "walletId": "<wallet-uuid>",
    "type": "X402_ALLOWED_DOMAINS",
    "rules": {
      "domains": ["api.example.com", "*.openai.com"]
    }
  }'

The agent can only auto-pay domains you've explicitly whitelisted. This is the policy engine enforcing boundaries — the agent operates autonomously within a defined permission set, not without constraints.

The Policy Engine: Autonomy With Guardrails

Autonomous doesn't mean uncontrolled. WAIaaS ships with a policy engine that has 21 policy types and 4 security tiers: INSTANT, NOTIFY, DELAY, and APPROVAL.

The four tiers map directly to how much trust you're extending to the agent for a given operation:

• INSTANT — Execute immediately, no notification
• NOTIFY — Execute immediately, send you a notification
• DELAY — Queue for N seconds, then execute (cancellable)
• APPROVAL — Require explicit human approval before anything moves

A spending limit policy ties the tier to transaction size:

curl -X POST http://127.0.0.1:3100/v1/policies \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{
    "walletId": "<wallet-uuid>",
    "type": "SPENDING_LIMIT",
    "rules": {
      "instant_max_usd": 100,
      "notify_max_usd": 500,
      "delay_max_usd": 2000,
      "delay_seconds": 900,
      "daily_limit_usd": 5000
    }
  }'

With this configuration, your agent can move up to $100 instantly (appropriate for x402 micro-payments and small operational costs), handle up to $500 with a notification sent to you, queue up to $2,000 with a 15-minute cancellation window, and anything larger requires your explicit sign-off. The policy system follows default-deny: transactions are blocked unless explicitly permitted.

The other 20 policy types cover things like token whitelists, contract whitelists, rate limits, time restrictions, DeFi-specific limits (max leverage for perpetuals, max loan-to-value for lending), and reputation thresholds for agent-to-agent interactions via ERC-8004. The full list is extensive precisely because real economic agents face a wide surface of risk.

Multi-Chain, Multi-Protocol DeFi Access

An agent operating in the token economy isn't just sending transfers. It might need to swap assets, provide liquidity, stake for yield, or take positions in prediction markets. WAIaaS integrates 15 DeFi protocol providers across 18 networks (2 chain types: EVM and Solana).

A Jupiter swap on Solana looks like this:

curl -X POST http://127.0.0.1:3100/v1/actions/jupiter-swap/swap \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wai_sess_<token>" \
  -d '{
    "inputMint": "So11111111111111111111111111111111111111112",
    "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount": "1000000000"
  }'

The agent authenticates with a session token, specifies the action and protocol, and the daemon handles routing, signing, and submission. The integrated protocols include Jupiter (Solana DEX aggregation), Aave V3 (lending), Hyperliquid (perpetual futures), Lido and Jito (liquid staking), LI.FI and Across (cross-chain bridging), Polymarket (prediction markets), and more. An agent with access to this surface can participate in DeFi markets as a first-class economic actor.

Before any of this executes against real funds, there's a dry-run mode:

curl -X POST http://127.0.0.1:3100/v1/transactions/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wai_sess_<token>" \
  -d '{
    "type": "TRANSFER",
    "to": "recipient-address",
    "amount": "0.1",
    "dryRun": true
  }'

Add "dryRun": true to any transaction and you get a simulation of the outcome without committing anything on-chain. For agents that need to reason about consequences before acting, this is the equivalent of a read-only preview of the world state post-action.

Transactions flow through a 7-stage pipeline: validate → auth → policy → wait → execute → confirm. Every stage is a checkpoint, and the gas condition feature means transactions can be queued to execute only when gas prices fall below a threshold — useful for an agent managing costs autonomously.

Getting a Self-Documenting Agent Wallet Running

Here's the minimal path from zero to a working agent wallet with API discovery enabled:

Step 1: Install and start

npm install -g @waiaas/cli
waiaas init
waiaas start

Step 2: Create a wallet and session

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": "trading-wallet", "chain": "solana", "environment": "mainnet"}'

curl -X POST http://127.0.0.1:3100/v1/sessions \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{"walletId": "<wallet-uuid>"}'

Step 3: Explore the API spec

curl http://127.0.0.1:3100/doc -o openapi.json
open http://127.0.0.1:3100/reference

Step 4: Configure policies before funding

Set at minimum a SPENDING_LIMIT and an ALLOWED_TOKENS whitelist (which is default-deny — the agent can't move tokens you haven't explicitly permitted).

Step 5: Connect to your agent framework

Use the TypeScript SDK (npm install @waiaas/sdk), the Python SDK (pip install waiaas), or the 45-tool MCP server (waiaas mcp setup --all) depending on how your agent is built. If you're using Claude Desktop, the MCP setup command auto-registers the wallet and generates the configuration JSON for you.

The Architecture Argument

There's a broader point here worth making explicit. The design decision to expose wallet operations as a self-documenting HTTP API — rather than a library or SDK that agents import directly — has meaningful consequences for how agent economies can scale.

A library coupling means every agent implementation needs to speak the same language, import the same dependencies, and handle key material directly. An HTTP service with an OpenAPI spec means any agent, in any language, built on any framework, can discover and use the wallet's capabilities through a standard interface. The spec becomes the contract. Discovery becomes runtime, not build-time.

This is the same architectural shift the web made from tight client-server coupling to REST. It's the same shift that made microservices composable. Applied to agent wallet infrastructure, it means the economic layer of agent systems can evolve independently of the agents themselves — new protocols, new chains, new policy types can be added to the daemon and immediately become discoverable to any connected agent.

The OpenAPI spec at /doc isn't just developer convenience. It's the mechanism by which autonomous agents can reason about what economic actions are available to them at any given moment.

What's Next

If you're building agents that need to operate economically — paying for APIs, managing DeFi positions, executing trades, or participating in agent-to-agent commerce — the infrastructure is here and working today. Start with the GitHub repository for the full codebase and self-hosting instructions, and visit the official site for documentation on the policy engine and SDK references.

The open question isn't whether agents will need wallets. It's whether the wallet infrastructure will be designed for agents or retrofitted from human-facing tools. WAIaaS is an answer to that question built from first principles.

• GitHub: https://github.com/waiaas/WAIaaS
• Official site: https://waiaas.ai