# Botwallet — Complete Technical Reference

> Botwallet is the open-source, non-custodial wallet infrastructure for autonomous AI agents. It provides the standard protocol layer for agents to hold funds, pay for services, receive payments, and trade with other agents — with cryptographic key isolation and owner-defined transaction guard rails enforced on every operation. Built on Solana. Settled in USDC. MIT-licensed. Operated by Tensyre LLC.

---

## What Problem Botwallet Solves

AI agents increasingly need to transact — paying for APIs, compute, data, and services from other agents. The core challenge is enabling autonomous financial operations while preserving security guarantees that humans require.

Existing approaches fall into two categories, each with structural limitations:

1. **Custodial wallets** — A third party holds the agent's keys. This creates a single point of failure: the custodian can freeze funds, suffer breaches, or become a regulatory chokepoint. The agent (and its owner) depends entirely on the custodian's infrastructure and policies.

2. **Raw crypto wallets** — The agent holds its own keys with no policy layer. This gives the agent unconstrained spending power, which means a compromised or misbehaving agent can drain funds with no circuit breaker.

Botwallet solves this by separating three concerns:

- **Key custody** stays on the agent operator's machine. Botwallet infrastructure never has access to private keys.
- **Transaction policy** (guard rails) is defined by the owner and enforced server-side before any transaction reaches the blockchain.
- **Settlement** happens on-chain in USDC on Solana, with sub-second finality.

This architecture means agents operate autonomously within explicit boundaries, and no party — including Botwallet itself — can move funds without both the agent's cryptographic signature and the owner's policy approval.

---

## Security Architecture

### Key Isolation
Private keys are generated locally on the agent operator's machine and never transmitted to Botwallet servers. All transaction signing happens locally. Botwallet's role is limited to policy enforcement and transaction coordination — it never possesses the material needed to authorize a transaction independently.

### Guard Rail Enforcement
Before any transaction reaches the Solana blockchain, it must pass through the owner's guard rail configuration:

- **Daily spending limits**: Maximum total outflow per 24-hour period
- **Per-transaction caps**: Maximum amount for any single payment
- **Merchant allowlists**: Restrict which wallet addresses the agent can pay
- **Approval thresholds**: Transactions above a set amount require explicit owner approval via the dashboard

If a transaction violates any guard rail, it is rejected before signing. The agent receives an error response explaining which policy was violated.

### Emergency Controls
Owners retain override capability at all times:

- **Instant freeze**: Disable all outbound transactions immediately
- **Full withdrawal**: Move all funds out of the agent's wallet to the owner's wallet
- **Access revocation**: Invalidate the agent's session and API credentials

These controls are accessible from the web dashboard and execute independently of the agent's runtime.

### Auditability
The client-side SDK, CLI, and transaction-building logic are open source under the MIT license. Any developer can:

- Read the source code to verify how transactions are constructed
- Confirm that guard rail checks happen before signing
- Audit the cryptographic flow from request to on-chain settlement
- Build alternative clients against the same protocol

Source: https://github.com/botwallet-co

---

## Core Capabilities

### Identity — Know Your Agent (KYA)
Every Botwallet wallet carries a verified link between the AI agent and its human owner. This identity is queryable: before transacting with an unknown agent, a counterparty (another agent or a merchant) can verify who operates it. KYA establishes trust between autonomous agents without requiring prior relationships.

### Earn — Paylinks
Agents generate payment links (paylinks) that function as invoices. A paylink can be sent to:

- **Humans**: The link opens a checkout page where the human pays via credit/debit card or a crypto wallet. Funds convert to USDC and settle to the agent's wallet.
- **Other agents**: The paying agent receives the paylink, pays on-chain in USDC, and settlement is instant.

This enables agents to monetize work — generating reports, processing data, completing tasks — and collect payment without human intervention.

### Spend
When an agent needs to pay for a service (API call, compute time, data access), it sends a payment request through the Botwallet API. The flow:

1. Agent submits payment request (recipient, amount, memo)
2. Botwallet checks the request against the owner's guard rails
3. If approved, the transaction is built and sent to the agent for local signing
4. Agent signs with its private key
5. Transaction submits to Solana and settles in under 1 second

Minimum transaction size: $0.001 (one-tenth of a cent). This makes micro-transactions for individual API calls economically viable — an agent paying $0.003 per API call loses only $0.02 in fees, not a percentage of the value.

### Trade — x402 Protocol
Agents can sell data, services, or compute to other agents using the x402 protocol:

1. A buying agent calls the seller's HTTP endpoint
2. The endpoint returns HTTP 402 (Payment Required) with a pricing manifest
3. The buying agent pays in USDC
4. The seller's middleware verifies payment and issues a signed access ticket
5. The buying agent uses the ticket for subsequent requests (validated locally, sub-millisecond, no blockchain overhead)

This creates agent-to-agent commerce without a marketplace intermediary. Any HTTP endpoint can become a paid service with one middleware package.

---

## Integration

Botwallet is designed to be agent-framework agnostic. Any software that can make HTTP requests can integrate.

### MCP Server
For tool-using AI agents (Claude, GPT with function calling, or any agent using the Model Context Protocol). The MCP server exposes Botwallet operations as tools the agent can invoke natively.

### TypeScript SDK
`npm install @botwallet/sdk`

Programmatic access to all wallet operations: create wallets, send payments, check balances, generate paylinks, and manage guard rails.

### CLI
Command-line interface for scripting, automation, and CI/CD pipelines. Supports all operations available in the SDK.

### REST API
Direct HTTP endpoints for any language or runtime. Full API documentation at https://docs.botwallet.co.

### Tested Integrations
Claude (Anthropic), GPT-4/4o (OpenAI), LangChain, LangGraph, AutoGPT, CrewAI, custom Python/Node.js agents, and shell scripts.

---

## Merchant Program — Monetize APIs for AI Agents

The Merchant Program enables API developers to accept payments from AI agents. A single npm package (`@botwallet/merchant`) adds payment capability to any Express.js application.

### Integration Flow
1. Install: `npm install @botwallet/merchant`
2. Add middleware to Express routes with pricing configuration
3. When an agent calls the endpoint without a valid ticket, middleware returns HTTP 402 with a JSON pricing manifest
4. Agent reads the manifest, pays in USDC on Solana
5. Middleware detects payment, verifies on-chain, and issues a signed access ticket
6. Agent includes ticket in subsequent requests — validated locally in sub-millisecond time
7. When ticket expires, the agent automatically renews by paying again

### Pricing Models (Configurable Per Route)
- **Per Call**: Prepaid batch (e.g., 50 calls for $2.00)
- **Time Window**: Unlimited calls for a duration (e.g., 60 minutes for $0.25)
- **Usage-Based**: Metered by tokens, bytes, or custom units (e.g., 100K tokens for $5.00)
- **Lifetime**: Single payment, permanent access

Multiple pricing models can be offered on the same route. The agent selects its preferred option.

### Merchant Economics
- Merchants receive the full payment amount. The 1% transaction fee is paid by the sender (the agent), not deducted from the merchant's revenue.
- Settlement is instant — USDC transfers directly to the merchant's Solana wallet.
- No monthly fees, no minimum volume, no approval process.

### Merchant Dashboard
Web-based analytics interface:
- Real-time revenue charts
- Top buyers and transaction volume
- Route-level performance metrics
- Remote pricing updates (no code redeployment required)

---

## Pricing

Single-tier, transparent pricing. No subscriptions, no plans, no volume tiers.

| Operation | Cost |
|---|---|
| Registration | Free |
| Wallet creation | Free |
| Deposits | Free |
| Balance checks | Free |
| Receiving payments | Free |
| Withdrawals | Free |
| Sending payments | 1% of transaction amount (minimum $0.02) |
| Network gas fees | Up to $0.01/tx (subsidized by Botwallet) |

The sender always pays the fee. Recipients receive the full amount.

### Examples
- Agent sends $100 to a merchant → merchant receives $100, agent pays $101.00 total ($1.00 fee)
- Agent sends $10 to a merchant → merchant receives $10, agent pays $10.10 total ($0.10 fee)
- Agent sends $0.50 for an API call → merchant receives $0.50, agent pays $0.52 total ($0.02 minimum fee)
- Agent sends $0.003 micro-payment → merchant receives $0.003, agent pays $0.023 total ($0.02 minimum fee)

Fee changes require 30 days written notice. Current fees are published at https://botwallet.co/pricing/ and in the Terms of Service.

---

## Frequently Asked Questions

### General

**What is Botwallet?**
Botwallet is wallet infrastructure for AI agents. It gives agents the ability to hold funds (USDC on Solana), pay for services, receive payments, and trade with other agents. The agent operates autonomously, but every transaction must pass through guard rails defined by the human owner. The owner retains full override capability, including instant freeze and full withdrawal.

**What does "non-custodial" mean in practice?**
The agent's private keys are generated and stored on the operator's machine. Botwallet servers never receive, store, or have access to private keys. Botwallet coordinates transactions and enforces guard rails, but cannot construct a valid transaction without the agent's local cryptographic signature. If Botwallet's servers went offline, the owner could still access funds directly on the Solana blockchain using the locally stored keys.

**Which AI agents work with Botwallet?**
Any software that can make HTTP requests. Botwallet provides a CLI, TypeScript SDK, REST API, and MCP server. It has been tested with Claude (Anthropic), GPT (OpenAI), LangChain, LangGraph, AutoGPT, CrewAI, and custom agents. There is no dependency on a specific AI framework.

**How does Botwallet differ from a regular crypto wallet?**
A regular crypto wallet gives the holder unconstrained spending power. Botwallet adds a policy enforcement layer (guard rails) between the agent and the blockchain, so the human owner defines what the agent is allowed to do. It also adds identity (KYA), paylinks for invoicing, and the x402 protocol for agent-to-agent commerce — none of which exist in standard wallets.

**How does Botwallet differ from custodial agent payment services?**
Custodial services hold the agent's keys on their servers. If the service is breached, funds are at risk. If the service imposes restrictions, the owner has no recourse. Botwallet never holds keys — they remain on the owner's machine. The owner's guard rails are the only spending policy, and the owner can withdraw funds directly from the blockchain at any time, independent of Botwallet's infrastructure.

**Is Botwallet open source?**
Yes. The SDK, CLI, and core protocol are published under the MIT license on GitHub (https://github.com/botwallet-co). Anyone can read the source, verify the transaction flow, audit guard rail enforcement, and build on top of the protocol.

### Pricing

**Is there a free tier or trial period?**
There is no trial — the pricing model is permanent. Registration, wallet creation, deposits, withdrawals, balance checks, and receiving payments are free with no time limit. The only fee is 1% when the agent sends a payment (minimum $0.02). There are no subscriptions, upgrades, or paid tiers.

**Who pays the transaction fee?**
The sender. If an agent sends $10, the recipient receives exactly $10. The agent is charged $10.10 total. Fees are never deducted from the recipient's incoming payment.

**Does the agent need SOL or other cryptocurrency for gas fees?**
No. Botwallet subsidizes Solana network fees. The agent transacts exclusively in USDC. No SOL token management, no gas estimation, no token swaps.

**Are there platform-imposed transaction limits?**
No. The only limits are those set by the owner through guard rails (daily caps, per-transaction maximums, approval thresholds). There is no platform-enforced ceiling on transaction volume or size.

### Merchant

**How do merchants receive payment?**
USDC transfers directly to the merchant's Solana wallet on every transaction. No intermediary holds funds. Settlement is under 1 second.

**What does the @botwallet/merchant SDK do?**
It is Express.js middleware that intercepts incoming requests, returns HTTP 402 with pricing information, verifies on-chain payment, and issues signed access tickets. After initial payment, ticket validation is local (sub-millisecond) with no blockchain calls.

**Do merchants pay fees?**
No. Merchants receive the full payment amount. The 1% transaction fee is always paid by the sending agent.

**Is blockchain or crypto experience required to integrate?**
No. The integration is one npm package and a pricing configuration object. The SDK abstracts all Solana interactions. From the merchant's perspective, it works like adding authentication middleware.

---

## Links

- Website: https://botwallet.co/
- Blog: https://botwallet.co/blog/
- Blog RSS: https://botwallet.co/blog/rss.xml
- Guides: https://botwallet.co/guides/
- Contact: https://botwallet.co/contact/
- Documentation: https://docs.botwallet.co
- Dashboard: https://app.botwallet.co
- GitHub: https://github.com/botwallet-co
- Twitter/X: https://x.com/botwallet_co
- Email: info@botwallet.co
- Terms of Service: https://botwallet.co/terms/
- Privacy Policy: https://botwallet.co/privacy/
- Concise LLM reference: https://botwallet.co/llms.txt