AgentaOS · PancheI · Mar 25, 2026 · Mar 19, 2026 · Mar 25, 2026
diff --git a/README.md b/README.md
@@ -39,9 +39,11 @@ Go to [app.agentaos.ai](https://app.agentaos.ai), create a wallet, set your guar
 
 ```bash
 npm install -g agentaos
-agenta login
-agenta init
-agenta send 0xRecipient 0.01
+agenta login                                    # opens browser — sign in + activate wallet
+agenta status                                   # account overview
+agenta pay checkout -a 50 -c EUR                # create a payment checkout
+agenta sub init --create --name trading-bot     # create an agent sub-account
+agenta sub send 0xRecipient 0.01                # send ETH from sub-account
 ```
 
 ### From code
@@ -82,6 +84,7 @@ agent.destroy();
 |---------|-----|--------------|
 | [`@agentaos/sdk`](packages/signer) | [![npm](https://img.shields.io/npm/v/@agentaos/sdk)](https://www.npmjs.com/package/@agentaos/sdk) | Threshold signing SDK — load shares, sign transactions, viem integration |
 | [`agentaos`](packages/wallet) | [![npm](https://img.shields.io/npm/v/agentaos)](https://www.npmjs.com/package/agentaos) | CLI + MCP server for AI assistants |
+| [`@agentaos/pay`](packages/pay) | [![npm](https://img.shields.io/npm/v/@agentaos/pay)](https://www.npmjs.com/package/@agentaos/pay) | Payment SDK — create checkouts, track payments |
 | [`@agentaos/core`](packages/core) | [![npm](https://img.shields.io/npm/v/@agentaos/core)](https://www.npmjs.com/package/@agentaos/core) | Interfaces and types (zero deps) |
 | [`@agentaos/engine`](packages/schemes) | [![npm](https://img.shields.io/npm/v/@agentaos/engine)](https://www.npmjs.com/package/@agentaos/engine) | CGGMP24 threshold ECDSA scheme |
 | [`@agentaos/chains`](packages/chains) | [![npm](https://img.shields.io/npm/v/@agentaos/chains)](https://www.npmjs.com/package/@agentaos/chains) | Ethereum chain adapter (viem) |
@@ -159,21 +162,43 @@ agent.destroy(); // Wipes share material from memory
 npm install -g agentaos
 ```
 
+**Account**
+
+| Command | What it does |
+|---------|--------------|
+| `agenta login` | Sign in via browser (device-code flow) |
+| `agenta status` | Account, wallet, and readiness overview |
+| `agenta logout` | Clear session |
+
+**Payments** — accept payments from humans and AI agents
+
+| Command | What it does |
+|---------|--------------|
+| `agenta pay checkout -a 50` | Create a checkout session |
+| `agenta pay get <sessionId>` | Get checkout details |
+| `agenta pay list` | List your checkouts |
+
+**Agent Sub-accounts** — autonomous wallets with guardrails
+
 | Command | What it does |
 |---------|--------------|
-| `agenta init` | Create or import a signer |
-| `agenta status` | Signer info and connection status |
-| `agenta balance` | ETH balance |
-| `agenta send <to> <amount>` | Send ETH — threshold-signed, policy-checked |
-| `agenta sign-message <msg>` | Sign an arbitrary message |
-| `agenta deploy <bytecode>` | Deploy a smart contract |
-| `agenta proxy` | JSON-RPC signing proxy for Foundry/Hardhat |
+| `agenta sub init --create --name bot1` | Create a sub-account |
+| `agenta sub init --import --name bot1 --api-key ... --api-secret ...` | Import existing |
+| `agenta sub send <to> <amount>` | Send ETH — threshold-signed, policy-checked |
+| `agenta sub balance` | ETH + token balances |
+| `agenta sub policies get` | View signing policies |
+| `agenta sub policies set --file p.json` | Set policies from JSON |
+| `agenta sub pause` / `resume` | Pause or resume signing |
+| `agenta sub proxy` | JSON-RPC signing proxy for Foundry/Hardhat |
+
+All commands support `--json` for machine-readable output (AI agents, CI/CD).
 
 ```bash
-agenta init
-agenta send 0xRecipient 0.01 --network base-sepolia
-agenta sign-message "proof-of-liveness"
-agenta proxy --port 8545  # then: forge script Deploy.s.sol --rpc-url http://localhost:8545 --broadcast
+agenta login
+agenta pay checkout -a 50 -c EUR -d "Invoice #42"
+agenta sub init --create --name trading-bot
+agenta sub send 0xRecipient 0.01 --network base-sepolia
+agenta sub proxy --port 8545  # then: forge script Deploy.s.sol --rpc-url http://localhost:8545 --broadcast
 ```
 
 ---
@@ -189,34 +214,51 @@ Connect any AI assistant to AgentaOS. Claude, Cursor, Windsurf — they sign tra
   "mcpServers": {
     "agenta": {
       "command": "npx",
-      "args": ["-y", "agentaos", "mcp"],
+      "args": ["-y", "agentaos"],
       "env": {
         "AGENTA_API_KEY": "your-api-key",
-        "AGENTA_API_SECRET": "your-api-secret"
+        "AGENTA_API_SECRET": "your-api-secret",
+        "AGENTAOS_GATEWAY_KEY": "sk_live_your-gateway-key"
       }
     }
   }
 }
 ```
 
-Your **API Key** and **API Secret** are generated when you create a wallet at [app.agentaos.ai](https://app.agentaos.ai). Copy them from the credentials screen.
+- **API Key** + **API Secret** — for wallet tools. Generated when you create a sub-account.
+- **Gateway Key** — for payment tools. Generated at [app.agentaos.ai](https://app.agentaos.ai) → API Keys.
+
+### Tools (21 total)
+
+**Payments**
+
+| Tool | What it does |
+|------|--------------|
+| `agenta_pay_create_checkout` | Create a checkout session |
+| `agenta_pay_get_checkout` | Get checkout status |
+| `agenta_pay_list_checkouts` | List checkouts |
+
+**Wallet**
 
-### Tools
+| Tool | What it does |
+|------|--------------|
+| `agenta_wallet_overview` | Address, balance, network |
+| `agenta_get_balances` | ETH + ERC-20 balances |
+| `agenta_send_eth` | Send ETH |
+| `agenta_send_token` | Send ERC-20 tokens |
+| `agenta_sign_message` | Sign a message |
+| `agenta_sign_typed_data` | Sign EIP-712 typed data |
+| `agenta_call_contract` | Write to a contract |
+| `agenta_read_contract` | Read contract state |
+| `agenta_simulate` | Simulate a transaction |
+
+**x402 (agent-to-agent payments)**
 
 | Tool | What it does |
 |------|--------------|
-| `wallet_overview` | Address, balance, network |
-| `get_balances` | ETH + ERC-20 balances |
-| `send_eth` | Send ETH |
-| `send_token` | Send ERC-20 tokens |
-| `sign_message` | Sign a message |
-| `sign_typed_data` | Sign EIP-712 typed data |
-| `call_contract` | Write to a contract |
-| `read_contract` | Read contract state |
-| `simulate` | Simulate a transaction |
-| `list_signers` | List configured signers |
-| `list_networks` | Supported networks |
-| `get_audit_log` | Signing history |
+| `agenta_x402_check` | Check if a URL requires payment |
+| `agenta_x402_discover` | Discover x402 payment requirements |
+| `agenta_x402_fetch` | Fetch a resource with x402 payment |
 
 ---
 
@@ -281,7 +323,7 @@ const sendETH = new DynamicStructuredTool({
 ### Foundry / Hardhat
 
 ```bash
-agenta proxy --port 8545
+agenta sub proxy --port 8545
 forge script Deploy.s.sol --rpc-url http://localhost:8545 --broadcast
 ```
 
@@ -330,8 +372,9 @@ Ethereum, Base, Arbitrum, Optimism, Polygon — mainnet and testnet. All EVM cha
 
 | Variable | Description |
 |----------|-------------|
-| `AGENTA_API_KEY` | API key — generated when you create a wallet |
+| `AGENTA_API_KEY` | API key — generated when you create a sub-account |
 | `AGENTA_API_SECRET` | API secret — your signing credential, shown once at creation |
+| `AGENTAOS_GATEWAY_KEY` | Gateway key for payment tools (`sk_live_...` or `sk_test_...`) |
 | `AGENTA_SERVER` | Optional — defaults to `https://api.agentaos.ai` |
 
 ---

diff --git a/examples/forge-proxy/README.md b/examples/forge-proxy/README.md
@@ -11,10 +11,11 @@ Deploy smart contracts using Foundry through AgentaOS signing proxy. The full pr
 ## Setup
 
 ```bash
-# Configure AgentaOS CLI
-agenta init
+# Sign in and create a sub-account
+agenta login
+agenta sub init --create --name forge-deployer
 
-# Verify your signer is active
+# Verify status
 agenta status
 ```
 
@@ -27,7 +28,7 @@ chmod +x deploy.sh
 
 ## How It Works
 
-1. `agenta proxy` starts an RPC proxy on port 8545
+1. `agenta sub proxy` starts an RPC proxy on port 8545
 2. The proxy intercepts `eth_sendTransaction` and `eth_signTransaction` calls
 3. Each transaction is signed via the interactive CGGMP24 protocol (2-of-3 MPC)
 4. The AgentaOS server enforces all configured policies before co-signing
@@ -39,7 +40,7 @@ This means you can use **any** Ethereum tooling (Foundry, Hardhat, ethers.js) wi
 
 ```bash
 # Start proxy in one terminal
-agenta proxy --port 8545
+agenta sub proxy --port 8545
 
 # In another terminal, deploy with Forge
 forge create --rpc-url http://localhost:8545 --unlocked \

diff --git a/examples/full-lifecycle/README.md b/examples/full-lifecycle/README.md
@@ -34,32 +34,34 @@ chmod +x demo.sh
 ## Manual Flow
 
 ```bash
-# Create a signer at app.agentaos.ai
-# The wizard gives you an API Key and API Secret (copy both).
+# Sign in and activate wallet
+agenta login
 
-# Configure the CLI
-agenta init
+# Create a sub-account
+agenta sub init --create --name demo
 
 # Send a transaction
-agenta send 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 0.001
+agenta sub send 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 0.001
 
 # Sign a message
-agenta sign-message "Hello from AgentaOS"
+agenta sub sign-message "Hello from AgentaOS"
 
 # Check status
 agenta status
 
 # Check balance
-agenta balance
+agenta sub balance
+
+# Create a payment checkout
+agenta pay checkout -a 50 -c EUR
 ```
 
 ## Policy Enforcement
 
-Add policies via [app.agentaos.ai](https://app.agentaos.ai):
+Set policies via the CLI or [app.agentaos.ai](https://app.agentaos.ai):
 
 ```bash
-# After adding a spending limit (max 0.1 ETH per tx) in the browser app,
-# try to send more than 0.1 ETH — it will be blocked with 403
-agenta send 0x... 0.5
+# After adding a spending limit, try to exceed it — blocked with 403
+agenta sub send 0x... 0.5
 # Error: Policy violation: spending_limit — amount exceeds limit
 ```
diff --git a/examples/full-lifecycle/demo.sh b/examples/full-lifecycle/demo.sh
@@ -46,26 +46,26 @@ echo ""
 echo ""
 
 # Step 2: CLI init + status
-echo "==> Step 2: Initialize CLI + check signer status"
-${CLI} init --server "${SERVER}" --non-interactive 2>/dev/null || echo "    (already initialized)"
+echo "==> Step 2: Initialize sub-account + check status"
+${CLI} sub init --create --name demo --server "${SERVER}" 2>/dev/null || echo "    (already initialized)"
 ${CLI} status
 echo ""
 
 # Step 3: Balance
-echo "==> Step 3: Check signer balance"
-${CLI} balance
+echo "==> Step 3: Check sub-account balance"
+${CLI} sub balance
 echo ""
 
 # Step 4: Sign a message
 echo "==> Step 4: Sign proof-of-liveness message"
 MSG="agenta-lifecycle-demo::$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 echo "    Message: ${MSG}"
-${CLI} sign-message "${MSG}"
+${CLI} sub sign-message "${MSG}"
 echo ""
 
 # Step 5: Send a transaction
 echo "==> Step 5: Send 0.000001 ETH (Base Sepolia)"
-${CLI} send 0x0000000000000000000000000000000000000001 0.000001
+${CLI} sub send 0x0000000000000000000000000000000000000001 0.000001
 echo ""
 
 # Step 6: Audit log

diff --git a/packages/pay/README.md b/packages/pay/README.md
@@ -87,7 +87,8 @@ const checkout = await agentaos.checkouts.create({
 |-------|------|-------------|
 | `id` | `string` | Session UUID |
 | `sessionId` | `string` | Public session ID (used in checkout URL) |
-| `checkoutUrl` | `string` | URL to send your customer to |
+| `checkoutUrl` | `string` | URL to send your human customer to |
+| `x402Url` | `string` | x402 protocol URL for AI agent payments |
 | `status` | `'open' \| 'completed' \| 'expired' \| 'cancelled'` | Current status |
 | `amountOverride` | `number \| null` | Amount for this session |
 | `currency` | `string` | Settlement currency |
@@ -152,7 +153,6 @@ console.log(link.checkoutUrl);
 |-------|------|-------------|
 | `id` | `string` | Link UUID |
 | `checkoutUrl` | `string` | Shareable payment URL |
-| `x402Url` | `string` | x402 protocol URL (for agent payments) |
 | `amount` | `number` | Payment amount |
 | `currency` | `string` | Settlement currency |
 | `status` | `'active' \| 'cancelled'` | Link status |

diff --git a/packages/pay/src/client.ts b/packages/pay/src/client.ts
@@ -26,8 +26,11 @@ export class AgentaOS {
 			);
 		}
 
-		// Validate key format
-		if (!apiKey || (!apiKey.startsWith('sk_live_') && !apiKey.startsWith('sk_test_'))) {
+		// Detect auth mode: API key (sk_live_/sk_test_) or JWT (Bearer token from CLI)
+		const isApiKey = apiKey.startsWith('sk_live_') || apiKey.startsWith('sk_test_');
+		const isJwt = !isApiKey && apiKey.includes('.') && apiKey.split('.').length === 3;
+
+		if (!isApiKey && !isJwt) {
 			throw new Error(
 				'Invalid API key format. Must start with sk_live_ or sk_test_.\n' +
 					'Get your key at: https://app.agentaos.ai → Settings → API Keys',
@@ -40,6 +43,7 @@ export class AgentaOS {
 			maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES,
 			debug: options?.debug ?? false,
 			logger: options?.logger as ((level: string, message: string) => void) | undefined,
+			authMode: isApiKey ? ('api-key' as const) : ('jwt' as const),
 		};
 
 		this.checkouts = new CheckoutsResource(baseUrl, apiKey, resourceOptions);

diff --git a/packages/pay/src/resources/base.ts b/packages/pay/src/resources/base.ts
@@ -9,6 +9,7 @@ export class BaseResource {
 			maxRetries: number;
 			debug?: boolean;
 			logger?: (level: string, message: string) => void;
+			authMode?: 'api-key' | 'jwt';
 		},
 	) {}
 
@@ -26,6 +27,7 @@ export class BaseResource {
 			maxRetries: this.options.maxRetries,
 			debug: this.options.debug,
 			logger: this.options.logger,
+			authMode: this.options.authMode,
 		});
 	}
 
@@ -41,6 +43,7 @@ export class BaseResource {
 			idempotencyKey,
 			debug: this.options.debug,
 			logger: this.options.logger,
+			authMode: this.options.authMode,
 		});
 	}
 
@@ -54,6 +57,7 @@ export class BaseResource {
 			maxRetries: this.options.maxRetries,
 			debug: this.options.debug,
 			logger: this.options.logger,
+			authMode: this.options.authMode,
 		});
 	}
 
@@ -71,6 +75,7 @@ export class BaseResource {
 			maxRetries: this.options.maxRetries,
 			debug: this.options.debug,
 			logger: this.options.logger,
+			authMode: this.options.authMode,
 		});
 	}
 
@@ -88,6 +93,7 @@ export class BaseResource {
 			maxRetries: this.options.maxRetries,
 			debug: this.options.debug,
 			logger: this.options.logger,
+			authMode: this.options.authMode,
 		});
 	}
 }
diff --git a/packages/pay/src/types.ts b/packages/pay/src/types.ts
@@ -93,7 +93,6 @@ export interface PaymentLink {
 	description: string | null;
 	status: 'active' | 'cancelled';
 	checkoutUrl: string;
-	x402Url: string;
 	metadata: Record<string, unknown>;
 	checkoutFields: CheckoutField[];
 	webhookUrl: string | null;
@@ -141,6 +140,8 @@ export interface CreateCheckoutParams {
 	cancelUrl?: string;
 	/** seconds, 300-86400, default 1800 */
 	expiresIn?: number;
+	/** CAIP-2 network IDs (e.g. ['eip155:8453']). Defaults to Base mainnet. */
+	supportedNetworks?: string[];
 }
 
 export interface ListCheckoutParams extends ListParams {
@@ -153,6 +154,7 @@ export interface Checkout {
 	orgId: string;
 	sessionId: string;
 	checkoutUrl: string;
+	x402Url: string;
 	status: 'open' | 'completed' | 'expired' | 'cancelled';
 	amountOverride: number | null;
 	currency: string;