@waiaas/skills 2.5.0 → 2.6.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waiaas/skills",
-  "version": "2.5.0",
+  "version": "2.6.0-rc.1",
   "description": "WAIaaS skill files for AI agents - install via npx @waiaas/skills add <name>",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "@types/node": "^22.0.0"
   },
   "scripts": {
-    "prebuild": "node scripts/sync-version.mjs",
+    "prebuild": "node scripts/sync-skills.mjs",
     "build": "tsc -p tsconfig.build.json",
     "clean": "rm -rf dist"
   }

package/skills/actions.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Actions"
 description: "Action Provider framework: list providers, execute DeFi actions through the 6-stage transaction pipeline"
 category: "api"
 tags: [wallet, blockchain, defi, actions, waiass]
-version: "2.5.0"
+version: "2.6.0-rc.1"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]
@@ -21,6 +21,16 @@ http://localhost:3100
 
 All action endpoints require **sessionAuth** via `Authorization: Bearer <token>` header.
 
+## Permissions
+
+### Agent (sessionAuth)
+- List action providers and their available actions
+- Execute actions (subject to policy evaluation)
+
+### Admin (masterAuth -- prerequisite)
+- Register API keys for action providers via Admin UI Settings
+- Configure CONTRACT_WHITELIST/ALLOWED_TOKENS policies for provider contracts
+
 ```
 Authorization: Bearer wai_sess_eyJ...
 ```

package/skills/admin.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Admin"
 description: "Admin API: daemon status, kill switch, notifications, settings management, JWT rotation, shutdown, oracle status, API key management"
 category: "api"
 tags: [wallet, blockchain, admin, security, oracle, defi, waiass]
-version: "2.5.0"
+version: "2.6.0-rc.1"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]
@@ -11,6 +11,8 @@ dispatch:
 
 # WAIaaS Admin API
 
+> **Operator only.** All admin endpoints require masterAuth (X-Master-Password). AI agents must NOT use these endpoints — they are for the Operator via Admin UI or CLI.
+
 Admin endpoints for daemon operations management. Covers health monitoring, emergency kill switch, notification channels, settings (RPC, security, notifications), JWT secret rotation, and graceful shutdown.
 
 ## Base URL
@@ -31,6 +33,60 @@ The master password is set in `config.toml` under `[security]` or via environmen
 
 ---
 
+## Session Creation (Multi-Wallet)
+
+### POST /v1/sessions -- Create Session (masterAuth)
+
+```bash
+curl -s -X POST http://localhost:3100/v1/sessions \
+  -H 'Content-Type: application/json' \
+  -H 'X-Master-Password: <password>' \
+  -d '{"walletIds": ["wallet-1-uuid", "wallet-2-uuid"], "defaultWalletId": "wallet-1-uuid"}'
+```
+
+Body:
+- `walletIds`: string[] -- Connect multiple wallets (new)
+- `walletId`: string -- Connect single wallet (backward compatible)
+- `defaultWalletId`?: string -- Specify default wallet (optional, defaults to first)
+- `expiresIn`?: number -- TTL in seconds
+
+## Session-Wallet Management (masterAuth required)
+
+Dynamic wallet management for existing sessions.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/v1/sessions/:id/wallets` | Add wallet `{ walletId }` |
+| DELETE | `/v1/sessions/:id/wallets/:walletId` | Remove wallet |
+| PATCH | `/v1/sessions/:id/wallets/:walletId/default` | Set default |
+| GET | `/v1/sessions/:id/wallets` | List connected wallets |
+
+Wallet addition/removal triggers `SESSION_WALLET_ADDED` / `SESSION_WALLET_REMOVED` notifications.
+
+## Agent Self-Discovery
+
+### GET /v1/connect-info (sessionAuth)
+
+Returns wallets, policies, capabilities, and AI prompt for the authenticated session.
+
+```bash
+curl -s http://localhost:3100/v1/connect-info \
+  -H 'Authorization: Bearer <session-token>'
+```
+
+### POST /admin/agent-prompt (masterAuth)
+
+Creates a multi-wallet session and returns a connection prompt with session token.
+
+```bash
+curl -s -X POST http://localhost:3100/v1/admin/agent-prompt \
+  -H 'Content-Type: application/json' \
+  -H 'X-Master-Password: <password>' \
+  -d '{"walletIds": ["wallet-1-uuid", "wallet-2-uuid"]}'
+```
+
+---
+
 ## 1. Daemon Status & Control
 
 > **See also:** `GET /health` (no auth required, includes version check info: `latestVersion`, `updateAvailable`, `schemaVersion`). Documented in **quickstart.skill.md** Step 1.

package/skills/policies.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Policies"
 description: "Policy engine CRUD: 12 policy types for spending limits, whitelists, time restrictions, rate limits, token/contract/approve controls, network restrictions, x402 domain controls"
 category: "api"
 tags: [wallet, blockchain, policies, security, waiass]
-version: "2.5.0"
+version: "2.6.0-rc.1"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]
@@ -11,6 +11,8 @@ dispatch:
 
 # WAIaaS Policy Management
 
+> **Policy CRUD (create/update/delete) is Operator only** (requires masterAuth). AI agents can read policies via GET endpoints with sessionAuth, but cannot modify them.
+
 Policy engine for enforcing rules on wallet operations. Policies control spending limits, allowed recipients, time windows, rate limits, token whitelists, contract access, approval requirements, and network restrictions.
 
 ## Base URL
@@ -19,22 +21,36 @@ Policy engine for enforcing rules on wallet operations. Policies control spendin
 http://localhost:3100
 ```
 
+## Permissions
+
+### Agent (sessionAuth)
+- **GET /v1/policies** -- Query policies applied to own wallet (filtered by session wallet)
+
+### Admin (masterAuth)
+- **GET /v1/policies** -- Query all policies (with optional walletId filter)
+- **POST /v1/policies** -- Create new policies
+- **PUT /v1/policies/{id}** -- Update existing policies
+- **DELETE /v1/policies/{id}** -- Delete policies
+
 ## Authentication
 
-All policy endpoints require **sessionAuth** -- include `Authorization: Bearer <token>` header from a session JWT.
+- **GET** accepts both `Authorization: Bearer <token>` (sessionAuth) and `X-Master-Password` (masterAuth).
+  - sessionAuth: returns only policies for the session's wallet + global policies.
+  - masterAuth: returns all policies (with optional walletId filter).
+- **POST/PUT/DELETE** require `X-Master-Password` (masterAuth) only.
 
 ---
 
 ## 1. Policy CRUD Endpoints
 
-### POST /v1/policies -- Create Policy
+### POST /v1/policies -- Create Policy (masterAuth)
 
 Create a new policy. Policies can be wallet-specific (`walletId`) or global (omit `walletId`).
 
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{
     "walletId": "<wallet-uuid>",
     "type": "SPENDING_LIMIT",
@@ -70,13 +86,18 @@ curl -s -X POST http://localhost:3100/v1/policies \
 }
 ```
 
-### GET /v1/policies -- List Policies
+### GET /v1/policies -- List Policies (sessionAuth or masterAuth)
 
-List policies. If `walletId` is provided, returns wallet-specific + global policies.
+List policies. Agents see only their own wallet's policies + global policies. Admins see all.
 
 ```bash
-curl -s 'http://localhost:3100/v1/policies?walletId=<wallet-uuid>' \
+# Agent (sessionAuth) -- auto-scoped to session wallet
+curl -s 'http://localhost:3100/v1/policies' \
   -H 'Authorization: Bearer <token>'
+
+# Admin (masterAuth) -- all policies or filtered
+curl -s 'http://localhost:3100/v1/policies?walletId=<wallet-uuid>' \
+  -H 'X-Master-Password: <password>'
 ```
 
 **Query Parameters:**
@@ -87,14 +108,14 @@ curl -s 'http://localhost:3100/v1/policies?walletId=<wallet-uuid>' \
 
 **Response (200):** Array of policy objects, ordered by priority descending.
 
-### PUT /v1/policies/{id} -- Update Policy
+### PUT /v1/policies/{id} -- Update Policy (masterAuth)
 
 Update a policy's rules, priority, or enabled state. All fields are optional (partial update).
 
 ```bash
 curl -s -X PUT http://localhost:3100/v1/policies/<policy-uuid> \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"rules": {"instant_max": "200000000", "notify_max": "1000000000", "delay_max": "2000000000"}, "enabled": true}'
 ```
 
@@ -108,11 +129,11 @@ curl -s -X PUT http://localhost:3100/v1/policies/<policy-uuid> \
 
 **Response (200):** Updated policy object.
 
-### DELETE /v1/policies/{id} -- Delete Policy
+### DELETE /v1/policies/{id} -- Delete Policy (masterAuth)
 
 ```bash
 curl -s -X DELETE http://localhost:3100/v1/policies/<policy-uuid> \
-  -H 'Authorization: Bearer <token>'
+  -H 'X-Master-Password: <password>'
 ```
 
 **Response (200):**
@@ -164,7 +185,7 @@ Maximum spend per tier. Amounts are digit strings in the chain's smallest unit (
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"SPENDING_LIMIT","rules":{"instant_max":"100000000","notify_max":"500000000","delay_max":"1000000000","daily_limit_usd":500,"monthly_limit_usd":5000}}'
 ```
 
@@ -186,7 +207,7 @@ Allowed recipient addresses. Transactions to addresses not in the list are block
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"WHITELIST","rules":{"allowed_addresses":["<addr1>","<addr2>"]}}'
 ```
 
@@ -210,7 +231,7 @@ Allowed time windows for transactions. Transactions outside the window are block
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"TIME_RESTRICTION","rules":{"allowedHours":{"start":9,"end":17},"timezone":"UTC"}}'
 ```
 
@@ -234,7 +255,7 @@ Maximum number of transactions per time period.
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"RATE_LIMIT","rules":{"maxTransactions":10,"period":"hourly"}}'
 ```
 
@@ -247,7 +268,7 @@ Token whitelist for TOKEN_TRANSFER transactions. **Default deny**: tokens not li
 {
   "tokens": [
     {"address": "<mint-or-contract>", "symbol": "USDC", "chain": "solana"},
-    {"address": "<erc20-address>", "symbol": "USDT", "chain": "ethereum"}
+    {"address": "<erc20-address>", "symbol": "USDT", "chain": "ethereum", "assetId": "eip155:1/erc20:<erc20-address>"}
   ]
 }
 ```
@@ -258,11 +279,14 @@ Token whitelist for TOKEN_TRANSFER transactions. **Default deny**: tokens not li
 | `address` | string | Yes      | Token mint (Solana) or contract address (EVM).   |
 | `symbol`  | string | No       | Token symbol for display (e.g., "USDC").         |
 | `chain`   | string | No       | "solana" or "ethereum". For documentation only.  |
+| `assetId` | string | No       | CAIP-19 asset identifier. Enables cross-chain matching. |
+
+**CAIP-19 matching:** When `assetId` is present in both the policy token entry and the transaction's token object, exact CAIP-19 matching is used (highest confidence). When only one side has `assetId`, the daemon extracts and compares addresses. When neither has `assetId`, legacy address-only matching is used. All 4 scenarios are backward compatible.
 
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"ALLOWED_TOKENS","rules":{"tokens":[{"address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","symbol":"USDC","chain":"solana"}]}}'
 ```
 
@@ -289,7 +313,7 @@ Contract address whitelist for CONTRACT_CALL transactions. **Default deny**: con
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"CONTRACT_WHITELIST","rules":{"contracts":[{"address":"0xE592427A0AEce92De3Edee1F18E0157C05861564","name":"Uniswap V3 Router","chain":"ethereum"}]}}'
 ```
 
@@ -321,7 +345,7 @@ Common EVM selectors:
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"METHOD_WHITELIST","rules":{"methods":[{"contractAddress":"0xE592427A0AEce92De3Edee1F18E0157C05861564","selectors":["0xa9059cbb","0x095ea7b3"]}]}}'
 ```
 
@@ -348,7 +372,7 @@ Allowed spender addresses for APPROVE transactions. **Default deny**: spenders n
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"APPROVED_SPENDERS","rules":{"spenders":[{"address":"0xE592427A0AEce92De3Edee1F18E0157C05861564","name":"Uniswap V3 Router","maxAmount":"1000000000000000000"}]}}'
 ```
 
@@ -372,7 +396,7 @@ Maximum approval amount and unlimited approval blocking for APPROVE transactions
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"APPROVE_AMOUNT_LIMIT","rules":{"maxAmount":"1000000000000000000","blockUnlimited":true}}'
 ```
 
@@ -394,7 +418,7 @@ Force a specific policy tier for all APPROVE transactions. Useful for requiring
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"APPROVE_TIER_OVERRIDE","rules":{"tier":"APPROVAL"}}'
 ```
 
@@ -421,7 +445,7 @@ Restrict which networks a wallet can use for transactions. Permissive by default
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"ALLOWED_NETWORKS","rules":{"networks":[{"network":"ethereum-sepolia"},{"network":"polygon-amoy"}]}}'
 ```
 
@@ -445,7 +469,7 @@ Allowed domains for x402 automatic payments. **Default deny**: if any X402_ALLOW
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"X402_ALLOWED_DOMAINS","rules":{"domains":["api.example.com","*.openai.com"]}}'
 ```
 
@@ -481,20 +505,20 @@ If no policies of a given default-deny type exist for a wallet, the check is ski
 
 ### Allow USDC token transfers
 
-1. Create ALLOWED_TOKENS policy to whitelist USDC:
+1. Create ALLOWED_TOKENS policy to whitelist USDC (with optional CAIP-19 assetId):
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
-  -d '{"walletId":"<uuid>","type":"ALLOWED_TOKENS","rules":{"tokens":[{"address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","symbol":"USDC"}]}}'
+  -H 'X-Master-Password: <password>' \
+  -d '{"walletId":"<uuid>","type":"ALLOWED_TOKENS","rules":{"tokens":[{"address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","symbol":"USDC","assetId":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}]}}'
 ```
 
 2. Send TOKEN_TRANSFER (see `transactions.skill.md` for full transaction reference):
 ```bash
 curl -s -X POST http://localhost:3100/v1/transactions/send \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
-  -d '{"type":"TOKEN_TRANSFER","to":"<recipient>","amount":"5000000","token":{"address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","decimals":6,"symbol":"USDC"}}'
+  -H 'X-Master-Password: <password>' \
+  -d '{"type":"TOKEN_TRANSFER","to":"<recipient>","amount":"5000000","token":{"address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","decimals":6,"symbol":"USDC","assetId":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}}'
 ```
 
 ### Allow Uniswap contract calls
@@ -503,7 +527,7 @@ curl -s -X POST http://localhost:3100/v1/transactions/send \
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"CONTRACT_WHITELIST","rules":{"contracts":[{"address":"0xE592427A0AEce92De3Edee1F18E0157C05861564","name":"Uniswap V3 Router"}]}}'
 ```
 
@@ -511,7 +535,7 @@ curl -s -X POST http://localhost:3100/v1/policies \
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"METHOD_WHITELIST","rules":{"methods":[{"contractAddress":"0xE592427A0AEce92De3Edee1F18E0157C05861564","selectors":["0x414bf389"]}]}}'
 ```
 
@@ -521,7 +545,7 @@ Create SPENDING_LIMIT with low tier thresholds:
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"SPENDING_LIMIT","rules":{"instant_max":"10000000","notify_max":"100000000","delay_max":"500000000"}}'
 ```
 
@@ -532,7 +556,7 @@ Any transfer exceeding `delay_max` (500M lamports = 0.5 SOL) requires owner appr
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"APPROVE_TIER_OVERRIDE","rules":{"tier":"APPROVAL"}}'
 ```
 
@@ -541,7 +565,7 @@ curl -s -X POST http://localhost:3100/v1/policies \
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"ALLOWED_NETWORKS","rules":{"networks":[{"network":"ethereum-sepolia"},{"network":"polygon-amoy"}]}}'
 ```
 
@@ -553,7 +577,7 @@ Prevent split-transaction bypass by limiting total USD spending per rolling wind
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
+  -H 'X-Master-Password: <password>' \
   -d '{"walletId":"<uuid>","type":"SPENDING_LIMIT","rules":{"instant_max":"100000000","notify_max":"500000000","delay_max":"1000000000","daily_limit_usd":500,"monthly_limit_usd":5000}}'
 ```
 

package/skills/quickstart.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Quickset"
 description: "End-to-end quickset: create wallet, session, check balance, send first transfer"
 category: "api"
 tags: [wallet, blockchain, solana, ethereum, quickset, quickstart, waiass]
-version: "2.5.0"
+version: "2.6.0-rc.1"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]
@@ -13,84 +13,42 @@ dispatch:
 
 WAIaaS (Wallet-as-a-Service for AI Agents) is a self-hosted local daemon that lets AI agents execute on-chain transactions on Solana and Ethereum with policy-based security controls. This guide walks through the complete workflow from creating your first wallet to sending a transaction.
 
-## 0. Connection Info
-
-### Magic Word (Agent Connection Prompt)
-
-If the user provides a `[WAIaaS Connection]` block, extract connection info and start API calls immediately:
-
-- `URL` -> API base URL
-- `Wallets` -> numbered list with wallet name, ID, network, session token
-- `Session` -> use as `Authorization: Bearer {token}` header
+## Base URL
 
-Example format:
 ```
-[WAIaaS Connection]
-- URL: http://localhost:3100
-
-Wallets:
-1. solana-testnet (019c6fb6-...) -- solana-devnet
-   Session: eyJhbG...
+http://localhost:3100
 ```
 
-### Session Renewal
+All endpoints use this base. The daemon runs locally on port 3100 by default.
 
-On `401 Unauthorized` response:
-1. Extract `sessionId` from JWT payload `sub` claim
-2. `POST /v1/wallets/{walletId}/sessions/{sessionId}/renew`
-3. Use the new token from response for subsequent requests
+## Authentication Model
 
-### No Connection Info?
+WAIaaS uses two authentication methods:
 
-Ask the user:
-"WAIaaS connection info is needed. Generate the agent prompt from the Admin UI dashboard (Dashboard > Agent Connection Prompt > Generate) and paste it here."
+| Auth Type | Header | Used For | Who |
+|-----------|--------|----------|-----|
+| **masterAuth** | `X-Master-Password: <password>` | Wallet creation, session creation, policy config, admin | **Operator only** |
+| **sessionAuth** | `Authorization: Bearer <token>` | Balance queries, transactions, wallet info, session renewal | AI agents |
 
-### Manual Discovery
+- **masterAuth** is for administrative operations performed by the **Operator** via Admin UI or CLI. AI agents must NEVER request or use the master password.
+- **sessionAuth** is for wallet-scoped operations. AI agents operate exclusively with session tokens (Bearer wai_sess_...).
 
-Check if the daemon is running and discover existing wallets before starting.
+## Self-Discovery (Recommended First Step)
 
-#### Health Check
+Call `GET /v1/connect-info` with your session token to discover:
+- Which wallets you can access
+- What policies apply to each wallet
+- Available capabilities (transfer, sign, x402, actions)
+- AI-ready prompt with usage instructions
 
 ```bash
-curl -s http://localhost:3100/health
+curl -s http://localhost:3100/v1/connect-info \
+  -H 'Authorization: Bearer <session-token>'
 ```
 
-If successful, you get `{"status":"ok", ...}`. If the daemon is not running, start it with `waiaas start`.
-
-#### List Existing Wallets (requires masterAuth)
+If using MCP, call the `connect_info` tool instead.
 
-```bash
-curl -s http://localhost:3100/v1/wallets \
-  -H 'X-Master-Password: <master-password>'
-```
-
-This returns all wallets. If wallets already exist, you can skip to Step 3 (Create a Session) using an existing wallet ID.
-
-> **Note**: The master password is the value set during `waiaas init`.
->
-> Skill files are API references. For interactive use with an AI agent,
-> set up the MCP server (`waiaas mcp setup`) or provide the daemon URL
-> and authentication credentials directly.
-
-## Base URL
-
-```
-http://localhost:3100
-```
-
-All endpoints use this base. The daemon runs locally on port 3100 by default.
-
-## Authentication Model
-
-WAIaaS uses two authentication methods:
-
-| Auth Type | Header | Used For |
-|-----------|--------|----------|
-| **masterAuth** | `X-Master-Password: <password>` | Wallet creation, session creation, wallet listing, token registry, MCP provisioning, admin |
-| **sessionAuth** | `Authorization: Bearer <token>` | Balance queries, transactions, wallet updates/deletion, session renewal |
-
-- **masterAuth** is for administrative operations. The master password is set in `config.toml` or via `WAIAAS_SECURITY_MASTER_PASSWORD` env var.
-- **sessionAuth** is for wallet-scoped operations. You get a JWT token by creating a session (Step 3 below). Each session is bound to one wallet.
+For multi-wallet sessions, specify `wallet_id` parameter to target a specific wallet. Omit to use the default wallet.
 
 ## Step-by-Step Workflow
 
@@ -125,7 +83,7 @@ Create a new wallet with a key pair. Requires **masterAuth**. Each wallet belong
 curl -s -X POST http://localhost:3100/v1/wallets \
   -H 'Content-Type: application/json' \
   -H 'X-Master-Password: your-master-password' \
-  -d '{"name": "my-first-wallet", "chain": "solana", "environment": "testnet"}'
+  -d '{"name": "my-first-wallet", "chain": "solana", "environment": "mainnet"}'
 ```
 
 **EVM wallet (Ethereum):**
@@ -134,13 +92,14 @@ curl -s -X POST http://localhost:3100/v1/wallets \
 curl -s -X POST http://localhost:3100/v1/wallets \
   -H 'Content-Type: application/json' \
   -H 'X-Master-Password: your-master-password' \
-  -d '{"name": "my-eth-wallet", "chain": "ethereum", "environment": "testnet"}'
+  -d '{"name": "my-eth-wallet", "chain": "ethereum", "environment": "mainnet"}'
 ```
 
 Parameters:
 - `name` (required): 1-100 characters
 - `chain` (optional): `"solana"` (default) or `"ethereum"`
-- `environment` (optional): `"testnet"` (default) or `"mainnet"` -- determines available networks
+- `environment` (optional): `"mainnet"` (default) or `"testnet"` -- determines available networks
+- `createSession` (optional): boolean, default `true` -- auto-creates a session and includes it in the response
 
 Response (201):
 ```json
@@ -148,45 +107,48 @@ Response (201):
   "id": "01958f3a-1234-7000-8000-abcdef123456",
   "name": "my-first-wallet",
   "chain": "solana",
-  "network": "devnet",
-  "environment": "testnet",
+  "network": "mainnet",
+  "environment": "mainnet",
   "publicKey": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
   "status": "ACTIVE",
-  "createdAt": 1707000000
+  "createdAt": 1707000000,
+  "session": {
+    "id": "01958f3b-5678-7000-8000-abcdef654321",
+    "token": "wai_sess_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "expiresAt": 1709592000
+  }
 }
 ```
 
-The `network` field shows the wallet's default network, automatically assigned based on the chain and environment. For Solana testnet, the default is `devnet`. For Ethereum testnet, the default is `ethereum-sepolia`.
+The `network` field shows the wallet's default network, automatically assigned based on the chain and environment. For Solana mainnet, the default is `mainnet`. For Ethereum mainnet, the default is `ethereum-mainnet`.
 
-Save the `id` value -- you need it to create a session.
+The `session` field contains the auto-created session token. Save the `token` value -- use it as `Authorization: Bearer <token>` for all wallet operations below. To skip auto-session creation, set `createSession: false`.
 
-### Step 3: Create a Session
+### Step 3: Create Additional Sessions (Optional)
 
-Create a session to get a JWT token for wallet operations. Requires **masterAuth**.
+A session is already created in Step 2. Use this only if you need additional sessions. Requires **masterAuth**.
 
 ```bash
 curl -s -X POST http://localhost:3100/v1/sessions \
   -H 'Content-Type: application/json' \
   -H 'X-Master-Password: your-master-password' \
-  -d '{"walletId": "01958f3a-1234-7000-8000-abcdef123456", "ttl": 86400}'
+  -d '{"walletId": "01958f3a-1234-7000-8000-abcdef123456", "ttl": 2592000}'
 ```
 
 Parameters:
 - `walletId` (required): UUID of the wallet from Step 2
-- `ttl` (optional): session lifetime in seconds, 300-604800 (default: 86400 = 24 hours)
+- `ttl` (optional): session lifetime in seconds, 300-31536000 (default: 2592000 = 30 days)
 
 Response (201):
 ```json
 {
   "id": "01958f3b-5678-7000-8000-abcdef654321",
   "token": "wai_sess_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-  "expiresAt": 1707086400,
+  "expiresAt": 1709592000,
   "walletId": "01958f3a-1234-7000-8000-abcdef123456"
 }
 ```
 
-Save the `token` value -- use it as `Authorization: Bearer <token>` for all wallet operations below.
-
 ### Step 4: Check Balance
 
 Get the native token balance (SOL for Solana, ETH for Ethereum). Requires **sessionAuth**.
@@ -203,7 +165,7 @@ Response:
 {
   "walletId": "01958f3a-1234-7000-8000-abcdef123456",
   "chain": "solana",
-  "network": "devnet",
+  "network": "mainnet",
   "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
   "balance": "1000000000",
   "decimals": 9,
@@ -229,7 +191,7 @@ Response:
 {
   "walletId": "01958f3a-1234-7000-8000-abcdef123456",
   "chain": "solana",
-  "network": "devnet",
+  "network": "mainnet",
   "assets": [
     {
       "mint": "So11111111111111111111111111111111111111112",
@@ -302,7 +264,7 @@ Response:
   "status": "CONFIRMED",
   "tier": "INSTANT",
   "chain": "solana",
-  "network": "devnet",
+  "network": "mainnet",
   "toAddress": "9aE476sH92Vz7DMPyq5WLPkrKWivxeuTKEFKd2sZZcde",
   "amount": "100000000",
   "txHash": "5UfD...abc",
@@ -323,10 +285,10 @@ Transaction status values:
 If you have the CLI installed, create wallets in one step:
 
 ```bash
-waiaas quickset --mode testnet
+waiaas quickset
 ```
 
-This creates Solana + EVM wallets and prints MCP configuration.
+This creates Solana + EVM wallets in mainnet mode (default) and prints MCP configuration. Use `--mode testnet` for testnet.
 
 ## Error Handling
 
@@ -363,5 +325,31 @@ Common error codes:
 - **transactions.skill.md** -- All 5 transaction types (TRANSFER, TOKEN_TRANSFER, CONTRACT_CALL, APPROVE, BATCH) with full parameters
 - **policies.skill.md** -- Policy management (spending limits, whitelists, rate limits, approval tiers)
 - **admin.skill.md** -- Admin operations (kill switch, status, settings, notifications)
-- **actions.skill.md** -- DeFi action providers: list and execute DeFi actions through the transaction pipeline
-- **x402.skill.md** -- x402 auto-payment protocol for fetching paid URLs with cryptocurrency
+
+## Asset Identification (CAIP-19)
+
+WAIaaS supports CAIP-19 standard asset identifiers for unambiguous cross-chain token identification. When sending token transfers, you can include an optional `assetId` field in the token object:
+
+```bash
+curl -s -X POST http://localhost:3100/v1/transactions/send \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer wai_sess_eyJ...' \
+  -d '{
+    "type": "TOKEN_TRANSFER",
+    "to": "9aE476sH92Vz7DMPyq5WLPkrKWivxeuTKEFKd2sZZcde",
+    "amount": "5000000",
+    "token": {
+      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+      "decimals": 6,
+      "symbol": "USDC",
+      "assetId": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
+    }
+  }'
+```
+
+CAIP-19 format: `{chain_id}/{asset_namespace}:{asset_reference}`
+- EVM tokens: `eip155:{chainId}/erc20:{lowercase_address}`
+- Solana tokens: `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:{base58_address}`
+- Native assets: `{chain_id}/slip44:{coin_type}` (ETH=60, SOL=501, POL=966)
+
+The `assetId` field is optional and backward compatible. See **transactions.skill.md** section 13 for full CAIP-19 reference.

package/skills/transactions.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Transactions"
 description: "All 5 transaction types (TRANSFER, TOKEN_TRANSFER, CONTRACT_CALL, APPROVE, BATCH) with lifecycle management"
 category: "api"
 tags: [wallet, blockchain, solana, ethereum, transactions, waiass]
-version: "2.5.0"
+version: "2.6.0-rc.1"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]
@@ -13,6 +13,20 @@ dispatch:
 
 Complete reference for all 5 transaction types, lifecycle management, and policy interaction. All endpoints use base URL `http://localhost:3100`. Transaction endpoints require **sessionAuth** (`Authorization: Bearer <token>`) unless noted otherwise.
 
+## Permissions
+
+### Agent (sessionAuth)
+- Send all 5 transaction types via `POST /v1/transactions/send`
+- Sign raw transactions via `POST /v1/transactions/sign`
+- Query transaction status and history
+- Renew session tokens
+
+### Owner (ownerAuth -- SIWS/SIWE)
+- Approve pending transactions via `POST /v1/transactions/{id}/approve`
+- Reject pending transactions via `POST /v1/transactions/{id}/reject`
+
+**Prerequisite:** Policy types (ALLOWED_TOKENS, CONTRACT_WHITELIST, APPROVED_SPENDERS) must be configured by admin before agents can use TOKEN_TRANSFER, CONTRACT_CALL, and APPROVE transaction types.
+
 ## 1. Overview
 
 WAIaaS uses a **discriminatedUnion 5-type** system for transactions. The `type` field in the request body determines which transaction variant to execute:
@@ -124,6 +138,7 @@ Parameters:
   - `address` (required): mint address (SPL) or contract address (ERC-20)
   - `decimals` (required): integer, 0-18
   - `symbol` (required): string, 1-10 characters
+  - `assetId` (optional): CAIP-19 asset identifier (e.g., `"eip155:1/erc20:0xa0b8..."`). Cross-validated against `address` when provided.
 - `memo` (optional): string, max 256 characters
 - `network` (optional): target network for this transaction. Defaults to wallet's default network. Must be valid for the wallet's environment.
 
@@ -250,6 +265,7 @@ Parameters:
   - `address` (required): token contract/mint address
   - `decimals` (required): integer, 0-18
   - `symbol` (required): string, 1-10 characters
+  - `assetId` (optional): CAIP-19 asset identifier. Cross-validated against `address` when provided.
 - `amount` (required): string of digits, max approval amount in token's smallest unit
 - `network` (optional): target network for this transaction. Defaults to wallet's default network. Must be valid for the wallet's environment.
 
@@ -705,3 +721,72 @@ curl -s -X POST http://localhost:3100/v1/utils/encode-calldata \
 - Python: `await client.encode_calldata(abi, function_name, args)`
 
 **MCP Tool:** `encode_calldata` with parameters `abi`, `functionName`, `args`
+
+## 13. CAIP-19 Asset Identification
+
+WAIaaS supports [CAIP-19](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-19.md) standard asset identifiers for cross-chain token identification. The `assetId` field is an optional addition to token objects in TOKEN_TRANSFER and APPROVE requests.
+
+### Format
+
+```
+{CAIP-2 chain ID}/{asset namespace}:{asset reference}
+```
+
+### Examples by Chain
+
+| Chain | Type | assetId | Description |
+|-------|------|---------|-------------|
+| Ethereum | ERC-20 | `eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48` | USDC on Ethereum Mainnet |
+| Polygon | ERC-20 | `eip155:137/erc20:0x3c499c542cef5e3811e1192ce70d8cc03d5c3359` | USDC on Polygon |
+| Solana | SPL | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | USDC on Solana Mainnet |
+| Ethereum | Native | `eip155:1/slip44:60` | ETH (native) |
+| Solana | Native | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/slip44:501` | SOL (native) |
+| Polygon | Native | `eip155:137/slip44:966` | POL (native) |
+
+**Important:** EVM addresses in CAIP-19 must be **lowercase** (not checksummed).
+
+### Usage in TOKEN_TRANSFER
+
+```bash
+curl -s -X POST http://localhost:3100/v1/transactions/send \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer wai_sess_eyJ...' \
+  -d '{
+    "type": "TOKEN_TRANSFER",
+    "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD16",
+    "amount": "5000000",
+    "token": {
+      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+      "decimals": 6,
+      "symbol": "USDC",
+      "assetId": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
+    }
+  }'
+```
+
+### Usage in APPROVE
+
+```bash
+curl -s -X POST http://localhost:3100/v1/transactions/send \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer wai_sess_eyJ...' \
+  -d '{
+    "type": "APPROVE",
+    "spender": "0xE592427A0AEce92De3Edee1F18E0157C05861564",
+    "token": {
+      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+      "decimals": 6,
+      "symbol": "USDC",
+      "assetId": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
+    },
+    "amount": "1000000000"
+  }'
+```
+
+### Cross-Validation
+
+When both `address` and `assetId` are provided, the daemon extracts the address from the CAIP-19 URI and validates it matches `token.address` (case-insensitive for EVM). If they don't match, the request is rejected with `ACTION_VALIDATION_FAILED`.
+
+### Backward Compatibility
+
+`assetId` is fully optional. Existing requests without `assetId` continue to work unchanged. You can gradually adopt CAIP-19 identifiers without breaking existing integrations.

package/skills/wallet.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Wallet Management"
 description: "Wallet CRUD, asset queries, session management, token registry, MCP provisioning, owner management"
 category: "api"
 tags: [wallet, blockchain, solana, ethereum, sessions, tokens, mcp, waiass]
-version: "2.5.0"
+version: "2.6.0-rc.1"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]
@@ -13,6 +13,24 @@ dispatch:
 
 Complete reference for wallet CRUD operations, asset queries, session management, token registry, MCP provisioning, and owner management. All endpoints use base URL `http://localhost:3100`.
 
+## Permissions
+
+### Agent (sessionAuth) — AI agents use these
+- Query wallet balance, assets, address, nonce, and info
+- Send transactions via transaction endpoints (see transactions.skill.md)
+- Get registered tokens via `GET /v1/tokens`
+- Get applied policies via `GET /v1/policies`
+
+### Operator only (masterAuth) — NOT for AI agents
+- Create/list/update/delete wallets
+- Create/list/delete sessions, manage session-wallet links
+- Create/delete MCP tokens
+- Register/remove custom tokens
+- Set owner addresses, default network, additional networks
+- WalletConnect pairing management
+
+> AI agents must NEVER request the master password. Use only your session token.
+
 ## 1. Wallet CRUD
 
 All wallet CRUD endpoints require **masterAuth** (`X-Master-Password` header), except `PUT /v1/wallets/{id}` and `DELETE /v1/wallets/{id}` which require **sessionAuth** (`Authorization: Bearer <token>`).
@@ -25,13 +43,13 @@ Create a new wallet with an auto-generated key pair. Each wallet belongs to an *
 curl -s -X POST http://localhost:3100/v1/wallets \
   -H 'Content-Type: application/json' \
   -H 'X-Master-Password: your-master-password' \
-  -d '{"name": "trading-bot", "chain": "solana", "environment": "testnet"}'
+  -d '{"name": "trading-bot", "chain": "solana", "environment": "mainnet"}'
 ```
 
 Parameters:
 - `name` (required): string, 1-100 characters
 - `chain` (optional): `"solana"` (default) or `"ethereum"`
-- `environment` (optional): `"testnet"` (default) or `"mainnet"` -- determines available networks and default network
+- `environment` (optional): `"mainnet"` (default) or `"testnet"` -- determines available networks and default network
 - `createSession` (optional): boolean, default `true` -- auto-creates a session token in the response
 
 Response (201):
@@ -40,8 +58,8 @@ Response (201):
   "id": "01958f3a-1234-7000-8000-abcdef123456",
   "name": "trading-bot",
   "chain": "solana",
-  "network": "devnet",
-  "environment": "testnet",
+  "network": "mainnet",
+  "environment": "mainnet",
   "publicKey": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
   "status": "ACTIVE",
   "createdAt": 1707000000,
@@ -70,8 +88,8 @@ Response (200):
       "id": "01958f3a-1234-7000-8000-abcdef123456",
       "name": "trading-bot",
       "chain": "solana",
-      "network": "devnet",
-      "environment": "testnet",
+      "network": "mainnet",
+      "environment": "mainnet",
       "publicKey": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
       "status": "ACTIVE",
       "createdAt": 1707000000
@@ -95,9 +113,9 @@ Response (200):
   "id": "01958f3a-1234-7000-8000-abcdef123456",
   "name": "trading-bot",
   "chain": "solana",
-  "network": "devnet",
-  "environment": "testnet",
-  "defaultNetwork": "devnet",
+  "network": "mainnet",
+  "environment": "mainnet",
+  "defaultNetwork": "mainnet",
   "publicKey": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
   "status": "ACTIVE",
   "ownerAddress": null,
@@ -165,8 +183,8 @@ Response (200):
   "id": "01958f3a-1234-7000-8000-abcdef123456",
   "name": "trading-bot",
   "chain": "solana",
-  "network": "devnet",
-  "environment": "testnet",
+  "network": "mainnet",
+  "environment": "mainnet",
   "publicKey": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
   "status": "ACTIVE",
   "ownerAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
@@ -244,18 +262,41 @@ Response (200):
 {
   "id": "01958f3a-1234-7000-8000-abcdef123456",
   "chain": "solana",
-  "environment": "testnet",
-  "defaultNetwork": "devnet",
+  "environment": "mainnet",
+  "defaultNetwork": "mainnet",
   "availableNetworks": [
-    {"network": "devnet", "isDefault": true},
-    {"network": "testnet", "isDefault": false}
+    {"network": "mainnet", "isDefault": true}
   ]
 }
 ```
 
-## 2. Wallet Query (Session-Scoped)
+## 2. Multi-Wallet Operations
+
+When your session has multiple wallets, you can target a specific wallet:
+- GET requests: add `?walletId=<id>` query parameter
+- POST requests: add `walletId` field in request body
+- Omitting walletId uses the session's default wallet
+
+Example:
+```bash
+GET /v1/wallet/balance?walletId=wallet-abc
+POST /v1/transactions/send { "walletId": "wallet-abc", "to": "...", "amount": "..." }
+```
+
+### Self-Discovery via connect-info
+
+Call `GET /v1/connect-info` (sessionAuth) to discover all accessible wallets, policies, and capabilities:
+
+```bash
+curl -s http://localhost:3100/v1/connect-info \
+  -H 'Authorization: Bearer <session-token>'
+```
+
+Returns wallets with their addresses and chains, applicable policies per wallet, available capabilities (transfer, token_transfer, balance, assets, sign, actions, x402), and an AI-ready prompt.
 
-These endpoints operate on the wallet bound to the session token. Require **sessionAuth**.
+## 3. Wallet Query (Session-Scoped)
+
+These endpoints operate on the wallet bound to the session token (or the specified walletId). Require **sessionAuth**.
 
 ### GET /v1/wallet/address -- Get Wallet Address
 
@@ -460,12 +501,13 @@ Response (200):
 
 Error: `ENVIRONMENT_NETWORK_MISMATCH` (400) if the specified network is not valid for the wallet's environment.
 
-## 3. Session Management
+## 4. Session Management
 
 Session creation and listing require **masterAuth**. Revocation requires **masterAuth**. Renewal requires **sessionAuth** (the session's own token).
 
 ### POST /v1/sessions -- Create Session (masterAuth)
 
+**Single wallet:**
 ```bash
 curl -s -X POST http://localhost:3100/v1/sessions \
   -H 'Content-Type: application/json' \
@@ -473,8 +515,18 @@ curl -s -X POST http://localhost:3100/v1/sessions \
   -d '{"walletId": "01958f3a-1234-7000-8000-abcdef123456", "ttl": 86400}'
 ```
 
+**Multi-wallet:**
+```bash
+curl -s -X POST http://localhost:3100/v1/sessions \
+  -H 'Content-Type: application/json' \
+  -H 'X-Master-Password: your-master-password' \
+  -d '{"walletIds": ["wallet-1-uuid", "wallet-2-uuid"], "defaultWalletId": "wallet-1-uuid"}'
+```
+
 Parameters:
-- `walletId` (required): UUID of the wallet
+- `walletId` (string): UUID of a single wallet (backward compatible)
+- `walletIds` (string[]): UUIDs of multiple wallets (mutually exclusive with walletId)
+- `defaultWalletId` (optional): specify default wallet (defaults to first in walletIds)
 - `ttl` (optional): session lifetime in seconds, 300-604800 (default: 86400 = 24 hours)
 - `constraints` (optional): custom constraints object
 
@@ -555,7 +607,7 @@ Safety checks: 50% TTL must have elapsed, max 30 renewals, 30-day absolute lifet
 
 Errors: `RENEWAL_TOO_EARLY` (403), `RENEWAL_LIMIT_REACHED` (403), `SESSION_REVOKED` (401), `SESSION_ABSOLUTE_LIFETIME_EXCEEDED` (403), `SESSION_RENEWAL_MISMATCH` (401).
 
-## 4. Token Registry (EVM Only)
+## 5. Token Registry (EVM Only)
 
 Manage the known token list for EVM networks. Token registry is UX-only -- adding/removing tokens here does NOT affect ALLOWED_TOKENS policy. Requires **masterAuth**.
 
@@ -638,7 +690,7 @@ Response (200):
 }
 ```
 
-## 5. MCP Token Provisioning (masterAuth)
+## 6. MCP Token Provisioning (masterAuth)
 
 One-stop provisioning for Claude Desktop MCP integration: creates a session, writes the JWT to a token file, and returns the Claude Desktop config snippet.
 
@@ -679,7 +731,7 @@ Response (201):
 
 Copy the `claudeDesktopConfig` object into your Claude Desktop `claude_desktop_config.json` under `mcpServers`.
 
-## 6. Auth Nonce
+## 7. Auth Nonce
 
 Public endpoint (no auth required). Returns a nonce for owner signature verification (SIWS for Solana, SIWE for Ethereum).
 
@@ -699,7 +751,7 @@ Response (200):
 
 The nonce is a random 32-byte hex string valid for 5 minutes. Used by owner wallets to construct SIWS/SIWE authentication signatures.
 
-## 7. Multi-Chain Notes
+## 8. Multi-Chain Notes
 
 ### Environment-Network Reference
 
@@ -722,9 +774,9 @@ The nonce is a random 32-byte hex string valid for 5 minutes. Used by owner wall
 | Batch transactions | Supported | Not supported (BATCH_NOT_SUPPORTED) |
 | Owner signature | SIWS (Sign-In With Solana) | SIWE (Sign-In With Ethereum) |
 
-## 8. MCP Tools Reference
+## 9. MCP Tools Reference
 
-The MCP server exposes 18 tools for AI agents. Key wallet management tools:
+The MCP server exposes 23 tools for AI agents. Key wallet management tools:
 
 ### set_default_network
 
@@ -753,7 +805,7 @@ Get all assets (native + tokens). Same `network` parameter support as `get_balan
 
 Combined wallet information including address, chain, environment, and available networks with their default status.
 
-## 9. CLI Commands
+## 10. CLI Commands
 
 ### waiaas wallet info
 
@@ -771,7 +823,7 @@ Changes the wallet's default network.
 waiaas wallet set-default-network polygon-amoy
 ```
 
-## 10. SDK Methods
+## 11. SDK Methods
 
 ### TypeScript SDK
 
@@ -814,7 +866,7 @@ async with WAIaaSClient("http://localhost:3100", "wai_sess_...") as client:
     all_assets = await client.get_all_assets()
 ```
 
-## 11. Error Reference
+## 12. Error Reference
 
 | Code | HTTP | Description |
 |------|------|-------------|
@@ -834,7 +886,7 @@ async with WAIaaSClient("http://localhost:3100", "wai_sess_...") as client:
 | `CHAIN_ERROR` | 502 | Blockchain RPC error |
 | `UNAUTHORIZED` | 401 | Missing or invalid auth header |
 
-## 12. WalletConnect Session Management
+## 13. WalletConnect Session Management
 
 WalletConnect allows the wallet owner to connect an external wallet (D'CENT, MetaMask, Phantom, etc.) to approve high-tier transactions. The daemon manages WC pairing, sessions, and signing bridges.
 
@@ -977,3 +1029,188 @@ async with WAIaaSClient("http://localhost:3100", "wai_sess_...") as client:
     result = await client.wc_disconnect()
     print(result.disconnected)  # True
 ```
+
+## 14. Wallet SDK: Notification Functions
+
+The `@waiaas/wallet-sdk` package provides functions for wallet apps to receive real-time notification events from the WAIaaS daemon.
+
+### subscribeToNotifications(topic, callback, serverUrl?)
+
+Subscribe to notification events via ntfy SSE stream. The daemon pushes notification events (transaction confirmations, policy violations, security alerts, etc.) to `waiaas-notify-{walletName}` ntfy topics.
+
+```typescript
+import { subscribeToNotifications } from '@waiaas/wallet-sdk';
+
+const subscription = subscribeToNotifications(
+  'waiaas-notify-trading-bot',   // ntfy topic
+  (notification) => {
+    console.log(notification.eventType);  // e.g. 'TX_CONFIRMED'
+    console.log(notification.category);   // e.g. 'transaction'
+    console.log(notification.title);      // Human-readable title
+    console.log(notification.body);       // Human-readable body
+  },
+  'https://ntfy.sh',  // optional, defaults to https://ntfy.sh
+);
+
+// Later: unsubscribe
+subscription.unsubscribe();
+```
+
+### parseNotification(data)
+
+Decode and validate a base64url-encoded NotificationMessage. Used internally by `subscribeToNotifications`, but also available for manual parsing.
+
+```typescript
+import { parseNotification } from '@waiaas/wallet-sdk';
+
+const notification = parseNotification(base64urlEncodedString);
+// notification: { version, eventType, walletId, walletName, category, title, body, details?, timestamp }
+```
+
+### NotificationMessage Type
+
+```typescript
+interface NotificationMessage {
+  version: '1';
+  eventType: string;        // One of 28 NotificationEventType values
+  walletId: string;         // UUID of the wallet
+  walletName: string;       // Human-readable wallet name
+  category: 'transaction' | 'policy' | 'security_alert' | 'session' | 'owner' | 'system';
+  title: string;            // Notification title
+  body: string;             // Notification body
+  details?: Record<string, unknown>;  // Optional event-specific details
+  timestamp: number;        // Unix epoch seconds
+}
+```
+
+### Notification Categories
+
+| Category | Events | ntfy Priority |
+|----------|--------|---------------|
+| transaction | TX_REQUESTED, TX_QUEUED, TX_SUBMITTED, TX_CONFIRMED, TX_FAILED, TX_CANCELLED, TX_DOWNGRADED_DELAY, TX_APPROVAL_REQUIRED, TX_APPROVAL_EXPIRED | 3 (default) |
+| policy | POLICY_VIOLATION, CUMULATIVE_LIMIT_WARNING | 3 (default) |
+| security_alert | WALLET_SUSPENDED, KILL_SWITCH_ACTIVATED, KILL_SWITCH_RECOVERED, KILL_SWITCH_ESCALATED, AUTO_STOP_TRIGGERED | **5 (urgent)** |
+| session | SESSION_EXPIRING_SOON, SESSION_EXPIRED, SESSION_CREATED, SESSION_WALLET_ADDED, SESSION_WALLET_REMOVED | 3 (default) |
+| owner | OWNER_SET, OWNER_REMOVED, OWNER_VERIFIED | 3 (default) |
+| system | DAILY_SUMMARY, LOW_BALANCE, APPROVAL_CHANNEL_SWITCHED, UPDATE_AVAILABLE | 3 (default) |
+
+## 15. Incoming Transactions
+
+Monitor and query incoming (received) transactions to your wallet. Requires **sessionAuth**.
+
+### GET /v1/wallet/incoming -- List Incoming Transactions (sessionAuth)
+
+List incoming transactions with cursor-based pagination and filters. By default, only confirmed transactions are returned.
+
+```bash
+curl -s http://localhost:3100/v1/wallet/incoming \
+  -H 'Authorization: Bearer wai_sess_xxx'
+```
+
+Query Parameters:
+- `limit` (optional): Max results, 1-100 (default: 20)
+- `cursor` (optional): Pagination cursor from previous response
+- `chain` (optional): Filter by chain (`solana` or `ethereum`)
+- `network` (optional): Filter by network (e.g., `devnet`, `ethereum-mainnet`)
+- `status` (optional): `DETECTED` or `CONFIRMED` (default: `CONFIRMED`)
+- `token` (optional): Filter by token address (omit for native transfers)
+- `from_address` (optional): Filter by sender address
+- `since` (optional): Only transactions detected after this epoch (seconds)
+- `until` (optional): Only transactions detected before this epoch (seconds)
+- `wallet_id` (optional): Target wallet ID (for multi-wallet sessions)
+
+Response (200):
+```json
+{
+  "data": [
+    {
+      "id": "01958f3a-1234-7000-8000-abcdef123456",
+      "txHash": "5VERv8NMvzbJ...",
+      "walletId": "01958f3a-0000-7000-8000-abcdef000001",
+      "fromAddress": "7xKXtg2CW87d...",
+      "amount": "1000000000",
+      "tokenAddress": null,
+      "chain": "solana",
+      "network": "devnet",
+      "status": "CONFIRMED",
+      "blockNumber": 280000000,
+      "detectedAt": 1707000000,
+      "confirmedAt": 1707000030,
+      "suspicious": false
+    }
+  ],
+  "nextCursor": "eyJkIjoxNzA3MDAwMDAwLCJpIjoiMDE5NThmM2EtMTIzNC03MDAwLTgwMDAtYWJjZGVmMTIzNDU2In0",
+  "hasMore": true
+}
+```
+
+### GET /v1/wallet/incoming/summary -- Incoming Transaction Summary (sessionAuth)
+
+Get period-based aggregated summary of incoming transactions with USD conversion.
+
+```bash
+curl -s 'http://localhost:3100/v1/wallet/incoming/summary?period=daily' \
+  -H 'Authorization: Bearer wai_sess_xxx'
+```
+
+Query Parameters:
+- `period` (optional): `daily`, `weekly`, or `monthly` (default: `daily`)
+- `chain` (optional): Filter by chain
+- `network` (optional): Filter by network
+- `since` (optional): Summary start epoch (seconds)
+- `until` (optional): Summary end epoch (seconds)
+- `wallet_id` (optional): Target wallet ID
+
+Response (200):
+```json
+{
+  "period": "daily",
+  "entries": [
+    {
+      "date": "2026-02-22",
+      "totalCount": 5,
+      "totalAmountNative": "5500000000",
+      "totalAmountUsd": 825.00,
+      "suspiciousCount": 0
+    }
+  ]
+}
+```
+
+### PATCH /v1/wallets/{id} -- Toggle Incoming Monitoring (masterAuth)
+
+Enable or disable incoming transaction monitoring for a specific wallet.
+
+```bash
+curl -s -X PATCH http://localhost:3100/v1/wallets/WALLET_ID \
+  -H 'Content-Type: application/json' \
+  -H 'X-Master-Password: your-master-password' \
+  -d '{"monitorIncoming": true}'
+```
+
+Response (200):
+```json
+{
+  "id": "01958f3a-0000-7000-8000-abcdef000001",
+  "monitorIncoming": true
+}
+```
+
+### MCP Tools
+
+- **list_incoming_transactions**: List incoming transaction history with filters and pagination.
+- **get_incoming_summary**: Get period-based incoming transaction summary (daily/weekly/monthly).
+
+### SDK Methods
+
+**TypeScript:**
+```typescript
+const incoming = await client.listIncomingTransactions({ limit: 10, status: 'CONFIRMED' });
+const summary = await client.getIncomingTransactionSummary({ period: 'weekly' });
+```
+
+**Python:**
+```python
+incoming = await client.list_incoming_transactions(limit=10, status="CONFIRMED")
+summary = await client.get_incoming_transaction_summary(period="weekly")
+```

package/skills/x402.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS x402"
 description: "x402 auto-payment protocol: fetch URLs with automatic cryptocurrency payments"
 category: "api"
 tags: [wallet, blockchain, x402, payments, waiass]
-version: "2.5.0"
+version: "2.6.0-rc.1"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]
@@ -21,6 +21,15 @@ http://localhost:3100
 
 Requires **sessionAuth** via `Authorization: Bearer <token>` header.
 
+## Permissions
+
+### Agent (sessionAuth)
+- Execute x402 fetch requests with automatic payment
+
+### Admin (masterAuth -- prerequisite)
+- Configure X402_ALLOWED_DOMAINS policy to whitelist payment target domains
+- Ensure wallet has USDC balance on the appropriate network
+
 ## 1. Fetch with Auto-Payment
 
 ### POST /v1/x402/fetch