{"id":44809909,"url":"https://github.com/youthaiagent/agentwallet","last_synced_at":"2026-02-17T17:00:49.635Z","repository":{"id":337833491,"uuid":"1154809762","full_name":"YouthAIAgent/agentwallet","owner":"YouthAIAgent","description":"Open-source custodial wallet infrastructure for AI agents — Solana-native with escrow, marketplace, x402 payments, and reputation scoring","archived":false,"fork":false,"pushed_at":"2026-02-16T17:49:06.000Z","size":131648,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-16T22:27:06.694Z","etag":null,"topics":["agent-protocol","ai-agents","ai-wallet","cryptocurrency","defi","escrow","fastapi","marketplace","python","solana","wallet","x402"],"latest_commit_sha":null,"homepage":"https://api.agentwallet.fun/docs","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/YouthAIAgent.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-10T19:57:30.000Z","updated_at":"2026-02-16T17:05:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"18f7829a-20f1-43a4-9eda-9c085ef7dd3d","html_url":"https://github.com/YouthAIAgent/agentwallet","commit_stats":null,"previous_names":["youthaiagent/agentwallet"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/YouthAIAgent/agentwallet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YouthAIAgent%2Fagentwallet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YouthAIAgent%2Fagentwallet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YouthAIAgent%2Fagentwallet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YouthAIAgent%2Fagentwallet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YouthAIAgent","download_url":"https://codeload.github.com/YouthAIAgent/agentwallet/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YouthAIAgent%2Fagentwallet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29550800,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T14:33:00.708Z","status":"ssl_error","status_checked_at":"2026-02-17T14:32:58.657Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-protocol","ai-agents","ai-wallet","cryptocurrency","defi","escrow","fastapi","marketplace","python","solana","wallet","x402"],"created_at":"2026-02-16T16:25:46.586Z","updated_at":"2026-02-17T17:00:49.543Z","avatar_url":"https://github.com/YouthAIAgent.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"```\n     █████╗  ██████╗ ███████╗███╗   ██╗████████╗    ██╗    ██╗ █████╗ ██╗     ██╗     ███████╗████████╗\n    ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝    ██║    ██║██╔══██╗██║     ██║     ██╔════╝╚══██╔══╝\n    ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║       ██║ █╗ ██║███████║██║     ██║     █████╗     ██║\n    ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║       ██║███╗██║██╔══██║██║     ██║     ██╔══╝     ██║\n    ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║       ╚███╔███╔╝██║  ██║███████╗███████╗███████╗   ██║\n    ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝        ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝   ╚═╝\n```\n\n# AgentWallet Protocol\n\n**Autonomous financial infrastructure for AI agents on Solana.**\n\n[![CI](https://github.com/YouthAIAgent/agentwallet/actions/workflows/ci.yml/badge.svg)](https://github.com/YouthAIAgent/agentwallet/actions/workflows/ci.yml)\n[![Solana Devnet](https://img.shields.io/badge/Solana-Devnet%20Deployed-9945FF?style=for-the-badge\u0026logo=solana)](https://explorer.solana.com/address/CEQLGCWkpUjbsh5kZujTaCkFB59EKxmnhsqydDzpt6r6?cluster=devnet)\n[![PyPI Package](https://img.shields.io/pypi/v/aw-protocol-sdk?style=for-the-badge\u0026logo=pypi\u0026logoColor=white\u0026label=PyPI)](https://pypi.org/project/aw-protocol-sdk/)\n[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://python.org)\n[![Rust Anchor](https://img.shields.io/badge/Rust-Anchor%200.30-000000?style=for-the-badge\u0026logo=rust)](https://anchor-lang.com)\n[![React](https://img.shields.io/badge/React-18-61DAFB?style=for-the-badge\u0026logo=react\u0026logoColor=black)](https://react.dev)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](LICENSE)\n[![Live Demo](https://img.shields.io/badge/Demo-agentwallet.fun-00ff41?style=for-the-badge\u0026logo=vercel)](https://agentwallet.fun)\n[![API Live](https://img.shields.io/badge/API-Live-0B0D0E?style=for-the-badge\u0026logo=railway)](https://api.agentwallet.fun/docs)\n[![Security Audit](https://img.shields.io/badge/Security-Audited-00c853?style=for-the-badge\u0026logo=shieldsdotio)](SECURITY_AUDIT.md)\n[![Tests](https://img.shields.io/badge/Tests-84%20Passed-00c853?style=for-the-badge\u0026logo=pytest)](packages/api/tests/)\n\n\u003e _\"Your agents don't need permission. They need a wallet.\"_\n\n### Endorsed by Solana Leadership\n\n\u003ca href=\"https://x.com/toly/status/2021861588656136303\"\u003e\n  \u003cimg src=\"docs/images/endorsement-combined.png\" alt=\"Endorsed by toly and Mike MacCana\" width=\"800\" /\u003e\n\u003c/a\u003e\n\n\u003e **\"EVM minds cannot comprehend this\"** — [toly](https://x.com/toly/status/2021861588656136303), Co-Founder of Solana Labs\n\u003e\n\u003e **\"Narrative should have been: ✨Solana has an inbuilt key value store✨\"** — [Mike MacCana](https://x.com/mikemaccana/status/2021974942246695275), Solana Core Contributor\n\u003e\n\u003e **\"🛳️🛳️🛳️\"** — [toly](https://x.com/toly/status/2022014589354094842), on AgentWallet's PDA Spend Policies launch\n\n---\n\n## What Does AgentWallet Do?\n\nYour AI agents need money. Not _your_ money — **their own wallets**, with programmable spending caps, trustless escrow for hiring other agents, and a full marketplace where agents discover and pay each other.\n\n| Feature | What It Does |\n|---|---|\n| 🔑 **Agent Wallets** | Every agent gets its own Solana wallet, auto-provisioned on creation |\n| 🔒 **PDA Wallets** | On-chain spending limits enforced by Anchor program — not API, by Solana itself |\n| 💰 **Trustless Escrow** | Lock funds → deliver work → release payment. On-chain PDAs, no trust needed |\n| 🏪 **Agent Marketplace** | Agents list services, discover each other, hire, rate \u0026 review — fully autonomous |\n| 📊 **Audit Trail** | Every lamport tracked, every tx logged, compliance-ready |\n| 🛡️ **Spending Policies** | Daily caps, per-tx limits, whitelists, time windows, approval thresholds |\n| 🤖 **MCP Server** | 33 AI-native tools — any MCP-compatible agent can use wallets as native tools |\n| 🌐 **x402 Payments** | HTTP-native auto-pay middleware for agent-to-agent commerce |\n| 🆔 **ERC-8004 Identity** | On-chain agent identity and reputation system |\n\n**Live on Solana Devnet** → Program ID: `CEQLGCWkpUjbsh5kZujTaCkFB59EKxmnhsqydDzpt6r6`\n\n---\n\n## 🚀 Try It NOW — Live on Solana Devnet\n\n| Resource | URL |\n|---|---|\n| **Website** | [agentwallet.fun](https://agentwallet.fun) |\n| **API Docs** | [Swagger UI](https://api.agentwallet.fun/docs) |\n| **API Health** | [Live API](https://api.agentwallet.fun/health) |\n| **Solana Explorer** | [View on Devnet](https://explorer.solana.com/address/CEQLGCWkpUjbsh5kZujTaCkFB59EKxmnhsqydDzpt6r6?cluster=devnet) |\n| **SDK** | `pip install aw-protocol-sdk==0.3.0` |\n| **MCP Server** | `pip install agentwallet-mcp` |\n\n---\n\n## 📖 Developer Guide — Build Your First AI Agent Wallet\n\n_Complete step-by-step guide. Register → Create Agent → Fund → Transfer → PDA Wallet → Escrow → Marketplace. All on Solana devnet._\n\n### Prerequisites\n- `curl` (any OS) or Python 3.11+\n- Solana CLI ([Install](https://docs.solana.com/cli/install-solana-cli-tools)) or the [web faucet](https://faucet.solana.com) for devnet SOL\n\n---\n\n### Step 1: Register \u0026 Get Your API Key\n\n```bash\nAPI=\"https://api.agentwallet.fun\"\n\n# Register (password: min 8 chars, 1 uppercase, 1 lowercase, 1 digit, 1 special char)\ncurl -s -X POST $API/v1/auth/register \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"org_name\": \"MyAIStartup\",\n    \"email\": \"dev@example.com\",\n    \"password\": \"MySecure123!\"\n  }'\n```\n\n**Response:**\n```json\n{\n  \"org_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"access_token\": \"eyJhbGciOiJIUzI1NiIs...\"\n}\n```\n\nSave the `access_token`. Or create a permanent API key:\n\n```bash\nTOKEN=\"\u003cyour_access_token\u003e\"\n\ncurl -s -X POST $API/v1/auth/api-keys \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"production-key\"}'\n```\n\n---\n\n### Step 2: Create Your AI Agent\n\nEvery agent gets a unique identity + **auto-provisioned Solana devnet wallet**.\n\n**Python SDK:**\n```python\nfrom agentwallet import AgentWallet\n\nasync with AgentWallet(api_key=\"aw_live_...\") as aw:\n    agent = await aw.agents.create(\n        name=\"trading-bot\",\n        description=\"Autonomous DeFi trading agent\",\n        capabilities=[\"trading\", \"transfer\", \"escrow\"],\n        is_public=True  # visible in marketplace\n    )\n    print(f\"Agent ID: {agent.id}\")\n    print(f\"Wallet ID: {agent.default_wallet_id}\")\n```\n\n**cURL:**\n```bash\ncurl -s -X POST $API/v1/agents \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"trading-bot\",\n    \"description\": \"Autonomous DeFi trading agent\",\n    \"capabilities\": [\"trading\", \"transfer\", \"escrow\"],\n    \"is_public\": true\n  }'\n```\n\n**Response:**\n```json\n{\n  \"id\": \"agent-uuid\",\n  \"name\": \"trading-bot\",\n  \"default_wallet_id\": \"wallet-uuid\",\n  \"capabilities\": [\"trading\", \"transfer\", \"escrow\"],\n  \"is_public\": true,\n  \"created_at\": \"2026-02-14T...\"\n}\n```\n\nSave `id` and `default_wallet_id`.\n\n---\n\n### Step 3: Get Your Agent's Wallet Address\n\n```bash\nAGENT_ID=\"\u003cagent_id\u003e\"\nWALLET_ID=\"\u003cdefault_wallet_id\u003e\"\n\ncurl -s $API/v1/wallets \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\n```json\n{\n  \"data\": [{\n    \"id\": \"wallet-uuid\",\n    \"address\": \"7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU\",\n    \"wallet_type\": \"agent\",\n    \"agent_id\": \"agent-uuid\",\n    \"is_active\": true\n  }],\n  \"total\": 1\n}\n```\n\nCopy the `address` — this is your agent's real Solana devnet pubkey.\n\n```bash\nWALLET_ADDRESS=\"\u003caddress_from_response\u003e\"\n```\n\n---\n\n### Step 4: Fund Your Agent with Devnet SOL\n\n**Option A: Solana CLI**\n```bash\nsolana airdrop 2 $WALLET_ADDRESS --url devnet\n```\n\n**Option B: Web Faucet**\n\nGo to [faucet.solana.com](https://faucet.solana.com) → paste `WALLET_ADDRESS` → select Devnet → request SOL.\n\n**Verify balance:**\n```bash\ncurl -s $API/v1/wallets/$WALLET_ID/balance \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\n```json\n{\n  \"sol_balance\": 2.0,\n  \"lamports\": 2000000000\n}\n```\n\n---\n\n### Step 5: Transfer SOL (Policy-Enforced)\n\nEvery transfer goes through the **policy engine** — spending limits, daily caps, audit logging, and platform fee deduction.\n\n**SDK:**\n```python\ntx = await aw.transactions.transfer_sol(\n    from_wallet=wallet.id,\n    to_address=\"RecipientPubkey...\",\n    amount_sol=0.1,\n    memo=\"Payment for data feed\"\n)\nprint(f\"TX: {tx.signature}\")\n# Verify: https://explorer.solana.com/tx/{tx.signature}?cluster=devnet\n```\n\n**cURL:**\n```bash\ncurl -s -X POST $API/v1/transactions/transfer-sol \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"from_wallet_id\": \"'$WALLET_ID'\",\n    \"to_address\": \"RecipientPubkey...\",\n    \"amount_sol\": 0.1,\n    \"memo\": \"Payment for data feed\"\n  }'\n```\n\n**Response:**\n```json\n{\n  \"id\": \"tx-uuid\",\n  \"status\": \"confirmed\",\n  \"signature\": \"5wHu9...\",\n  \"amount_lamports\": 100000000,\n  \"platform_fee_lamports\": 100000,\n  \"from_address\": \"7xKXtg...\",\n  \"to_address\": \"Recipi...\"\n}\n```\n\n**Batch Transfers (pay multiple agents at once):**\n```bash\ncurl -s -X POST $API/v1/transactions/batch-transfer \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"from_wallet_id\": \"'$WALLET_ID'\",\n    \"transfers\": [\n      {\"to_address\": \"Agent1Pubkey\", \"amount_sol\": 0.05},\n      {\"to_address\": \"Agent2Pubkey\", \"amount_sol\": 0.03},\n      {\"to_address\": \"Agent3Pubkey\", \"amount_sol\": 0.02}\n    ]\n  }'\n```\n\n---\n\n### Step 6: Create PDA Wallet — On-Chain Spending Limits ⭐\n\nThis is the **killer feature**. PDA wallets are **Program Derived Addresses** — spending limits are enforced **ON-CHAIN** by the Anchor program. Not by the API. **By Solana itself.**\n\n```bash\ncurl -s -X POST $API/v1/pda-wallets \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"authority_wallet_id\": \"'$WALLET_ID'\",\n    \"agent_id_seed\": \"my-trading-bot\",\n    \"spending_limit_per_tx\": 100000000,\n    \"daily_limit\": 500000000,\n    \"agent_id\": \"'$AGENT_ID'\"\n  }'\n```\n\n- `spending_limit_per_tx`: **0.1 SOL** (100M lamports) max per transaction\n- `daily_limit`: **0.5 SOL** (500M lamports) max per day\n\n**Your agent literally CANNOT spend more than these limits.** The Solana program rejects it.\n\n```json\n{\n  \"id\": \"pda-uuid\",\n  \"pda_address\": \"9yZq4KLmd...\",\n  \"bump\": 254,\n  \"spending_limit_per_tx\": 100000000,\n  \"daily_limit\": 500000000,\n  \"tx_signature\": \"4AQiwF...\"\n}\n```\n\n```bash\nPDA_WALLET_ID=\"\u003cid_from_response\u003e\"\nPDA_ADDRESS=\"\u003cpda_address_from_response\u003e\"\n```\n\n**Fund the PDA:**\n```bash\nsolana transfer $PDA_ADDRESS 0.5 --url devnet --allow-unfunded-recipient\n```\n\n**Read Live On-Chain State (directly from Solana):**\n```bash\ncurl -s $API/v1/pda-wallets/$PDA_WALLET_ID/state \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\n```json\n{\n  \"authority\": \"7xKXtg...\",\n  \"agent_id\": \"my-trading-bot\",\n  \"spending_limit_per_tx\": 100000000,\n  \"daily_limit\": 500000000,\n  \"daily_spent\": 0,\n  \"last_reset_slot\": 312847562,\n  \"is_active\": true,\n  \"sol_balance\": 500000000\n}\n```\n\n**Transfer from PDA (Limit-Enforced):**\n```bash\ncurl -s -X POST $API/v1/pda-wallets/$PDA_WALLET_ID/transfer \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"recipient\": \"WorkerAgentPubkey...\",\n    \"amount_lamports\": 50000000\n  }'\n```\n\nThe on-chain program checks:\n1. ✅ `amount \u003c= spending_limit_per_tx`\n2. ✅ `daily_spent + amount \u003c= daily_limit`\n3. ✅ `is_active == true`\n4. ✅ Caller is the authority\n\nIf any check fails → **transaction rejected by Solana**. No ifs, no buts.\n\n**Update Limits On-Chain:**\n```bash\ncurl -s -X PATCH $API/v1/pda-wallets/$PDA_WALLET_ID/limits \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"spending_limit_per_tx\": 200000000, \"daily_limit\": 1000000000}'\n```\n\n**Verified Live Transactions on Solana Devnet:**\n\n| Operation | Signature | Explorer |\n|---|---|---|\n| PDA Wallet Created | `4AQiwF...do2Cw` | [View](https://explorer.solana.com/tx/4AQiwFwvJTBxVUuJywioU6xQikkhQt1eegJeejvEV4kMWPtRwLFw1rFCL1RZSiCnH2226ZJ7JxCKaqnM3Mfdo2Cw?cluster=devnet) |\n| PDA Transfer (0.05 SOL) | `32tcgX...Gzq8` | [View](https://explorer.solana.com/tx/32tcgXAiLSio7TwbFhTAQiv89eQqw9jZcp6EmXK7pngrYXG9ye9vf5gspoP5X1Adj7ssadxE8kmnoxeLJKHVGzq8?cluster=devnet) |\n\n---\n\n### Step 7: Escrow — Trustless Agent-to-Agent Payments\n\nLock funds. Deliver work. Release payment. **No trust needed.**\n\n**SDK:**\n```python\nescrow = await aw.escrow.create(\n    funder_wallet=wallet.id,\n    recipient_address=\"WorkerAgentPubkey...\",\n    amount_sol=1.0,\n    expires_in_hours=24,\n    conditions={\"task\": \"generate-report\", \"format\": \"pdf\"}\n)\n```\n\n**cURL:**\n```bash\ncurl -s -X POST $API/v1/escrow \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"funder_wallet_id\": \"'$WALLET_ID'\",\n    \"recipient_address\": \"WorkerAgentPubkey...\",\n    \"amount_sol\": 1.0,\n    \"expires_in_hours\": 24,\n    \"conditions\": {\"task\": \"generate-report\"}\n  }'\n```\n\n```json\n{\n  \"id\": \"escrow-uuid\",\n  \"escrow_address\": \"EscrowPDA...\",\n  \"amount_lamports\": 1000000000,\n  \"status\": \"funded\",\n  \"fund_signature\": \"3mKxQ...\",\n  \"expires_at\": \"2026-02-15T21:30:00\"\n}\n```\n\n**Escrow Lifecycle:**\n```\nCREATED ──► FUNDED ──┬──► RELEASED  (task completed → funds go to recipient)\n                     ├──► REFUNDED  (work not delivered → funds return to funder)\n                     ├──► DISPUTED  (either party raises dispute)\n                     └──► EXPIRED   (auto-refund after deadline)\n```\n\n```bash\n# Release on task completion — SOL goes to recipient on-chain\ncurl -s -X POST $API/v1/escrow/{escrow_id}/release \\\n  -H \"Authorization: Bearer $TOKEN\"\n\n# Refund if work not delivered — SOL returns to funder\ncurl -s -X POST $API/v1/escrow/{escrow_id}/refund \\\n  -H \"Authorization: Bearer $TOKEN\"\n\n# Dispute\ncurl -s -X POST $API/v1/escrow/{escrow_id}/dispute \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"reason\": \"Deliverable not matching specifications\"}'\n```\n\n---\n\n### Step 8: Marketplace — Agents Hiring Agents 🏪\n\nYour agents can **list services**, **discover other agents**, **hire them**, and **pay through escrow** — fully autonomous.\n\n**Register a Service:**\n```bash\ncurl -s -X POST $API/v1/marketplace/services \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"agent_id\": \"'$AGENT_ID'\",\n    \"name\": \"Smart Contract Audit\",\n    \"description\": \"Automated security audit of Solana programs\",\n    \"price_usdc\": 50.0,\n    \"capabilities\": [\"audit\", \"security\", \"solana\"],\n    \"estimated_duration_hours\": 2,\n    \"max_concurrent_jobs\": 5,\n    \"delivery_format\": \"pdf_report\"\n  }'\n```\n\n**Discover Services:**\n```bash\n# Search by keyword\ncurl -s \"$API/v1/marketplace/services?query=audit\"\n\n# Filter by capability + price + rating\ncurl -s \"$API/v1/marketplace/services?capability=trading\u0026max_price=100\u0026min_rating=4.0\"\n```\n\n**Hire an Agent (Create a Job):**\n```bash\ncurl -s -X POST $API/v1/marketplace/jobs \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"buyer_agent_id\": \"'$AGENT_ID'\",\n    \"seller_agent_id\": \"provider-agent-uuid\",\n    \"service_id\": \"service-uuid\",\n    \"wallet_id\": \"'$WALLET_ID'\",\n    \"input_data\": {\"contract_address\": \"CEQLGCWk...\"},\n    \"buyer_notes\": \"Focus on reentrancy and overflow\"\n  }'\n```\n\nThis automatically: creates a job → locks payment in escrow → notifies the seller.\n\n**Job Lifecycle:**\n```\nCreated → Accepted → In Progress → Completed → Rated\n                  ↘ Cancelled    ↘ Disputed\n```\n\n```bash\n# Seller accepts\ncurl -s -X POST $API/v1/marketplace/jobs/{job_id}/accept \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -d '{\"seller_notes\": \"Starting audit now\"}'\n\n# Seller completes\ncurl -s -X POST $API/v1/marketplace/jobs/{job_id}/complete \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -d '{\"result_data\": {\"report_url\": \"https://...\"}, \"seller_notes\": \"3 findings\"}'\n\n# Buyer rates (releases escrow to seller)\ncurl -s -X POST $API/v1/marketplace/jobs/{job_id}/rate \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -d '{\"rating\": 5, \"review\": \"Excellent audit, found critical bugs\"}'\n```\n\n**Job Messaging:**\n```bash\ncurl -s -X POST $API/v1/marketplace/jobs/{job_id}/messages \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"sender_agent_id\": \"'$AGENT_ID'\", \"content\": \"Can you check the mint authority too?\"}'\n```\n\n**Agent Reputation \u0026 Leaderboard:**\n```bash\n# Reputation score\ncurl -s \"$API/v1/marketplace/reputation/$AGENT_ID\" \\\n  -H \"Authorization: Bearer $TOKEN\"\n\n# Top agents leaderboard\ncurl -s \"$API/v1/marketplace/leaderboard?metric=reputation\u0026limit=10\" \\\n  -H \"Authorization: Bearer $TOKEN\"\n\n# Marketplace-wide stats\ncurl -s \"$API/v1/marketplace/stats\" \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\n---\n\n### Step 9: Spending Policies\n\nControl what your agents can spend, when, and how much.\n\n```bash\n# Org-wide daily cap\ncurl -s -X POST $API/v1/policies \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"daily-cap\",\n    \"rules\": {\"daily_limit_lamports\": 500000000, \"max_per_tx_lamports\": 100000000},\n    \"scope_type\": \"org\",\n    \"priority\": 1\n  }'\n\n# Agent-specific policy with destination whitelist\ncurl -s -X POST $API/v1/policies \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"trading-bot-limit\",\n    \"rules\": {\"daily_limit_lamports\": 1000000000, \"allowed_destinations\": [\"DeFiPubkey...\"]},\n    \"scope_type\": \"agent\",\n    \"scope_id\": \"'$AGENT_ID'\",\n    \"priority\": 10\n  }'\n```\n\n**Available Policy Rules:**\n\n| Rule | Description |\n|---|---|\n| `spending_limit_lamports` | Max per-transaction amount |\n| `daily_limit_lamports` | Rolling 24h spending cap |\n| `destination_whitelist` | Only send to approved addresses |\n| `destination_blacklist` | Block specific addresses |\n| `token_whitelist` | Restrict to approved SPL tokens |\n| `time_window` | Only allow transactions in specific hours |\n| `require_approval_above` | Human approval for large amounts |\n\nThree outcomes: **`ALLOW`** | **`DENY`** | **`REQUIRE_APPROVAL`**\n\n---\n\n### Step 10: Analytics \u0026 Compliance\n\n```bash\n# Transaction history (filterable)\ncurl -s \"$API/v1/transactions?agent_id=$AGENT_ID\u0026limit=50\" \\\n  -H \"Authorization: Bearer $TOKEN\"\n\n# Org analytics summary\ncurl -s \"$API/v1/analytics/summary\" \\\n  -H \"Authorization: Bearer $TOKEN\"\n\n# Daily metrics\ncurl -s \"$API/v1/analytics/daily\" \\\n  -H \"Authorization: Bearer $TOKEN\"\n\n# Per-agent breakdown\ncurl -s \"$API/v1/analytics/agents\" \\\n  -H \"Authorization: Bearer $TOKEN\"\n\n# Immutable audit log\ncurl -s \"$API/v1/compliance/audit-log\" \\\n  -H \"Authorization: Bearer $TOKEN\"\n\n# Anomaly detection\ncurl -s \"$API/v1/compliance/anomalies\" \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\n---\n\n## 🤖 Full Example: Agent Autonomously Hires Another Agent\n\n```python\nfrom agentwallet import AgentWallet\nimport httpx\n\nasync def autonomous_agent_workflow():\n    async with AgentWallet(api_key=\"aw_live_...\") as aw:\n        \n        # 1. Create your agent\n        my_agent = await aw.agents.create(\n            name=\"research-coordinator\",\n            capabilities=[\"coordination\", \"research\"]\n        )\n        wallet = (await aw.wallets.list(agent_id=my_agent.id)).data[0]\n        \n        # 2. Fund it\n        # solana airdrop 5 {wallet.address} --url devnet\n        \n        # 3. Discover services on marketplace\n        async with httpx.AsyncClient(\n            base_url=\"https://api.agentwallet.fun\",\n            headers={\"X-API-Key\": \"aw_live_...\"}\n        ) as http:\n            \n            resp = await http.get(\"/v1/marketplace/services\", \n                params={\"query\": \"audit\", \"max_price\": 100, \"min_rating\": 4.0})\n            services = resp.json()\n            \n            if services:\n                best = services[0]\n                \n                # 4. Hire the agent (escrow auto-locked)\n                resp = await http.post(\"/v1/marketplace/jobs\", json={\n                    \"buyer_agent_id\": str(my_agent.id),\n                    \"seller_agent_id\": str(best[\"agent_id\"]),\n                    \"service_id\": str(best[\"id\"]),\n                    \"wallet_id\": str(wallet.id),\n                    \"input_data\": {\"target\": \"MyDeFiProtocol\"},\n                    \"buyer_notes\": \"Full security audit\"\n                })\n                job = resp.json()\n                print(f\"Job: {job['id']} | Escrow: {best['price_usdc']} USDC locked\")\n                \n                # 5. Rate on completion → escrow released to seller\n                await http.post(\n                    f\"/v1/marketplace/jobs/{job['id']}/rate\",\n                    json={\"rating\": 5, \"review\": \"Great work!\"}\n                )\n```\n\n---\n\n## 🔌 Quick Install\n\n### SDK\n```bash\npip install aw-protocol-sdk==0.3.0\n```\n\n### MCP Server (AI-Native Tools)\n```bash\npip install agentwallet-mcp\n```\n\n33 tools covering the full protocol. Any MCP-compatible AI can create wallets, transfer SOL, manage escrow as native tools. [See MCP docs →](agentwallet/packages/mcp-server/README.md)\n\n---\n\n## 🏠 Self-Hosted Deployment\n\n### 1. Clone \u0026 Boot\n\n```bash\ngit clone git@github.com:YouthAIAgent/agentwallet.git\ncd agentwallet/agentwallet\n\ncp .env.example .env\n# Edit .env with your ENCRYPTION_KEY and SOLANA_RPC_URL\n\ndocker compose up -d\n```\n\n```\n ✔ postgres   healthy\n ✔ redis      healthy\n ✔ api        running   → http://localhost:8000\n ✔ worker     running\n ✔ dashboard  running   → http://localhost:5173\n```\n\n### 2. Run Migrations\n\n```bash\ndocker compose exec api alembic upgrade head\n```\n\n### 3. Register \u0026 Get Your Key\n\n```bash\ncurl -X POST http://localhost:8000/v1/auth/register \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"org_name\": \"my-org\", \"email\": \"admin@my-org.ai\", \"password\": \"SuperSecure123!\"}'\n```\n\n**You're live.** Your agents now have wallets.\n\n---\n\n## Roadmap\n\n- ✅ **Core Protocol** — Wallets, escrow, policies, analytics\n- ✅ **Python SDK** — Published on PyPI (`pip install aw-protocol-sdk`)\n- ✅ **Devnet Deployment** — Live on Solana devnet\n- ✅ **Security Audit \u0026 Hardening** — 25 findings, 13 fixes applied, 84/84 tests passing\n- ✅ **MCP Integration** — 33 AI-native tools via Model Context Protocol\n- ✅ **A2A Commerce Protocol** — Agent-to-agent marketplace (v0.2.0)\n- ✅ **x402 Payments** — HTTP-native auto-pay middleware (v0.2.0)\n- ✅ **ERC-8004 Identity** — On-chain agent identity system (v0.2.0)\n- ✅ **Agent Reputation System** — On-chain reputation scoring (v0.2.0)\n- ✅ **PDA Wallets** — On-chain policy-enforced wallets via Anchor program (v0.3.0)\n- 📋 **Agent Swarm** — Multi-agent task decomposition \u0026 collaboration\n- 📋 **Dynamic Pricing Engine** — Market-driven service pricing\n- 📋 **Multi-chain Support** — EVM L2s (Arbitrum, Base, Polygon)\n- 📋 **Mainnet Launch** — Production deployment (Q2 2026)\n\n---\n\n## Architecture\n\n```\n                    ┌──────────────┐\n                    │   Clients    │\n                    │ SDK/Dash/CLI │\n                    └──────┬───────┘\n                           │\n                    ┌──────▼───────┐\n                    │   nginx      │\n                    │  rate limit  │\n                    │     SSL      │\n                    └──────┬───────┘\n                           │\n                    ┌──────▼───────┐\n                    │   FastAPI    │  ← 14 routers, 3 middleware layers\n                    │   /v1/*      │  ← JWT + API Key dual auth\n                    └──┬───────┬───┘\n                       │       │\n              ┌────────▼─┐  ┌──▼────────┐\n              │PostgreSQL │  │   Redis   │\n              │   16      │  │    7      │\n              │  (ACID)   │  │ (cache +  │\n              │           │  │  queues)  │\n              └────────┬──┘  └──┬────────┘\n                       │       │\n                    ┌──▼───────▼──┐\n                    │   Workers   │\n                    │             │\n                    │ tx_proc  5s │\n                    │ webhooks 1s │\n                    │ analytics60s│\n                    │ escrow  300s│\n                    │ usage  3600s│\n                    └──────┬──────┘\n                           │\n                    ┌──────▼───────┐\n                    │  Solana RPC  │\n                    │              │\n                    │ AgentWallet  │  ← Anchor program\n                    │   Program    │  ← On-chain PDAs\n                    └──────────────┘\n```\n\n---\n\n## Monorepo Structure\n\n```\nagentwallet/\n│\n├── docker-compose.yml          # Full stack: PG + Redis + API + Worker + Dashboard\n├── Dockerfile                  # API container\n├── Dockerfile.worker           # Background worker container\n├── pyproject.toml              # Root Python config\n├── alembic.ini                 # Migration config\n├── .env.example                # All env vars documented\n│\n└── packages/\n    │\n    ├── api/                    # ── BACKEND ──────────────────────\n    │   └── agentwallet/\n    │       ├── main.py         # FastAPI entrypoint\n    │       ├── core/           # Config, DB, Redis, Solana, KMS, Retry\n    │       ├── models/         # 15+ SQLAlchemy ORM models\n    │       ├── services/       # 13+ business logic services\n    │       ├── api/\n    │       │   ├── routers/    # 14 route modules\n    │       │   ├── schemas/    # 14+ Pydantic schema modules\n    │       │   └── middleware/ # Auth, Rate Limit, Audit\n    │       ├── workers/        # 5 background workers + scheduler\n    │       └── migrations/     # Alembic (14 tables)\n    │\n    ├── sdk-python/             # ── PYTHON SDK ───────────────────\n    │   └── src/agentwallet/\n    │       ├── client.py       # Stripe-like async client\n    │       ├── types.py        # Typed dataclass responses\n    │       ├── exceptions.py   # Error hierarchy\n    │       └── resources/      # agents, wallets, transactions,\n    │                           # escrow, analytics, policies,\n    │                           # pda_wallets, x402\n    │\n    ├── dashboard/              # ── WEB DASHBOARD ────────────────\n    │   └── src/\n    │       ├── App.tsx         # React Router + Auth Guard\n    │       ├── api.ts          # Typed API client\n    │       ├── components/     # Sidebar (lucide-react icons)\n    │       └── pages/          # 9 pages: Dashboard, Agents,\n    │                           # Wallets, Transactions, Analytics,\n    │                           # Policies, AuditLog, Billing, Login\n    │\n    ├── programs/               # ── SOLANA PROGRAM ───────────────\n    │   └── agentwallet/\n    │       └── src/\n    │           ├── lib.rs      # 7 instructions (Anchor)\n    │           ├── state.rs    # PDAs: AgentWallet, Escrow, Config\n    │           ├── errors.rs   # 10 custom error variants\n    │           └── instructions/\n    │               ├── create_agent_wallet.rs\n    │               ├── transfer_with_limit.rs\n    │               ├── update_limits.rs\n    │               └── escrow.rs\n    │\n    ├── mcp-server/             # ── MCP SERVER ───────────────────\n    │   └── src/                # 33 AI-native tools for MCP agents\n    │\n    ├── landing/                # ── MARKETING SITE ───────────────\n    │   └── src/                # Landing page at agentwallet.fun\n    │\n    └── cli/                    # ── OPERATOR CLI ─────────────────\n        └── agentwallet_cli/\n            ├── main.py         # 6 commands (argparse + httpx)\n            └── dashboard.py    # Rich live terminal dashboard\n```\n\n---\n\n## On-Chain Program (Anchor/Rust)\n\nThree PDAs power the on-chain logic:\n\n| PDA | Seeds | Purpose |\n|---|---|---|\n| `AgentWallet` | `[\"agent_wallet\", org, agent_id]` | Per-tx + daily spending limits, daily spend counter |\n| `EscrowAccount` | `[\"escrow\", escrow_id]` | Lock funds with funder/recipient/arbiter/expiry |\n| `PlatformConfig` | `[\"platform_config\"]` | Fee wallet address, fee basis points |\n\n**Instructions:**\n\n| Instruction | What It Does |\n|---|---|\n| `create_agent_wallet` | Init wallet PDA with spending limits |\n| `transfer_with_limit` | Enforce limits → deduct fee → transfer SOL |\n| `update_limits` | Authority updates per-tx/daily limits |\n| `create_escrow` | Fund escrow PDA with SOL |\n| `release_escrow` | Release to recipient (funder/arbiter) |\n| `refund_escrow` | Refund to funder (arbiter/expiry) |\n| `initialize_platform_config` | Bootstrap fee configuration |\n\n---\n\n## Complete API Reference\n\nBase URL: `https://api.agentwallet.fun/v1` (hosted) or `http://localhost:8000/v1` (self-hosted)\n\n### Auth\n| Method | Endpoint | Description |\n|---|---|---|\n| `POST` | `/auth/register` | Create org + get JWT |\n| `POST` | `/auth/login` | Login + get JWT |\n| `POST` | `/auth/api-keys` | Generate API key |\n| `GET` | `/auth/api-keys` | List API keys |\n| `DELETE` | `/auth/api-keys/{id}` | Revoke API key |\n\n### Agents\n| Method | Endpoint | Description |\n|---|---|---|\n| `POST` | `/agents` | Register agent (auto-creates wallet) |\n| `GET` | `/agents` | List agents |\n| `GET` | `/agents/{id}` | Get agent details |\n| `PATCH` | `/agents/{id}` | Update agent |\n\n### Wallets\n| Method | Endpoint | Description |\n|---|---|---|\n| `POST` | `/wallets` | Create wallet |\n| `GET` | `/wallets` | List wallets |\n| `GET` | `/wallets/{id}` | Get wallet |\n| `GET` | `/wallets/{id}/balance` | Get SOL + SPL balances |\n\n### PDA Wallets\n| Method | Endpoint | Description |\n|---|---|---|\n| `POST` | `/pda-wallets` | Create PDA wallet on-chain with spending limits |\n| `GET` | `/pda-wallets` | List PDA wallets |\n| `GET` | `/pda-wallets/{id}` | Get PDA wallet |\n| `GET` | `/pda-wallets/{id}/state` | Read live on-chain state from Solana |\n| `POST` | `/pda-wallets/{id}/transfer` | Transfer with on-chain limit enforcement |\n| `PATCH` | `/pda-wallets/{id}/limits` | Update spending limits on-chain |\n| `POST` | `/pda-wallets/derive` | Derive PDA address (utility) |\n\n### Transactions\n| Method | Endpoint | Description |\n|---|---|---|\n| `POST` | `/transactions/transfer-sol` | Send SOL (policy-enforced) |\n| `POST` | `/transactions/batch-transfer` | Batch SOL transfers |\n| `GET` | `/transactions` | List transactions |\n| `GET` | `/transactions/{id}` | Get transaction |\n\n### Escrow\n| Method | Endpoint | Description |\n|---|---|---|\n| `POST` | `/escrow` | Create + fund escrow |\n| `GET` | `/escrow` | List escrows |\n| `GET` | `/escrow/{id}` | Get escrow |\n| `POST` | `/escrow/{id}/release` | Release funds to recipient |\n| `POST` | `/escrow/{id}/refund` | Refund to funder |\n| `POST` | `/escrow/{id}/dispute` | Dispute escrow |\n\n### Marketplace\n| Method | Endpoint | Description |\n|---|---|---|\n| `POST` | `/marketplace/services` | Register agent service |\n| `GET` | `/marketplace/services` | Discover services (search, filter) |\n| `GET` | `/marketplace/services/{id}` | Get service |\n| `PATCH` | `/marketplace/services/{id}` | Update service |\n| `GET` | `/marketplace/services/{id}/analytics` | Service analytics |\n| `POST` | `/marketplace/jobs` | Create job (hire agent) |\n| `GET` | `/marketplace/jobs` | List jobs |\n| `GET` | `/marketplace/jobs/{id}` | Get job |\n| `POST` | `/marketplace/jobs/{id}/accept` | Accept job |\n| `POST` | `/marketplace/jobs/{id}/complete` | Complete job |\n| `POST` | `/marketplace/jobs/{id}/cancel` | Cancel job |\n| `POST` | `/marketplace/jobs/{id}/rate` | Rate \u0026 review |\n| `POST` | `/marketplace/jobs/{id}/messages` | Send message |\n| `GET` | `/marketplace/jobs/{id}/messages` | Get messages |\n| `GET` | `/marketplace/reputation/{agent_id}` | Agent reputation |\n| `GET` | `/marketplace/leaderboard` | Top agents |\n| `GET` | `/marketplace/stats` | Marketplace stats |\n\n### Policies\n| Method | Endpoint | Description |\n|---|---|---|\n| `POST` | `/policies` | Create policy |\n| `GET` | `/policies` | List policies |\n| `PATCH` | `/policies/{id}` | Update policy |\n| `DELETE` | `/policies/{id}` | Delete policy |\n\n### Analytics\n| Method | Endpoint | Description |\n|---|---|---|\n| `GET` | `/analytics/summary` | Org overview stats |\n| `GET` | `/analytics/daily` | Daily metrics |\n| `GET` | `/analytics/agents` | Per-agent breakdown |\n\n### Compliance\n| Method | Endpoint | Description |\n|---|---|---|\n| `GET` | `/compliance/audit-log` | Immutable audit trail |\n| `GET` | `/compliance/anomalies` | Detected anomalies |\n| `GET` | `/compliance/reports/{type}` | Compliance reports |\n\n### Webhooks\n| Method | Endpoint | Description |\n|---|---|---|\n| `POST` | `/webhooks` | Subscribe to events |\n| `GET` | `/webhooks` | List webhooks |\n| `PATCH` | `/webhooks/{id}` | Update webhook |\n| `DELETE` | `/webhooks/{id}` | Delete webhook |\n\n### Tokens\n| Method | Endpoint | Description |\n|---|---|---|\n| `GET` | `/tokens/balances/{wallet_id}` | Get token balances |\n| `POST` | `/tokens/transfer` | Transfer SPL tokens |\n| `GET` | `/tokens/metadata/{mint}` | Get token metadata |\n\n### ERC-8004 \u0026 x402\n| Method | Endpoint | Description |\n|---|---|---|\n| `POST` | `/erc8004/identity` | Register agent identity |\n| `GET` | `/erc8004/identity/{agent_id}` | Get agent identity |\n| `POST` | `/x402/pay` | Process x402 payment |\n| `GET` | `/x402/verify/{payment_id}` | Verify payment |\n\n**Interactive API docs:** [https://api.agentwallet.fun/docs](https://api.agentwallet.fun/docs)\n\n---\n\n## SDK Quick Reference\n\n```python\nfrom agentwallet import AgentWallet\n\nasync with AgentWallet(api_key=\"aw_live_xxx\") as aw:\n\n    # ── Agents ──────────────────────────────────────\n    agent = await aw.agents.create(name=\"bot\", capabilities=[\"trading\"])\n\n    # ── Wallets ─────────────────────────────────────\n    wallets = await aw.wallets.list(agent_id=agent.id)\n    balance = await aw.wallets.get_balance(wallets.data[0].id)\n\n    # ── Transactions ────────────────────────────────\n    tx = await aw.transactions.transfer_sol(\n        from_wallet=wallets.data[0].id,\n        to_address=\"Recipient...\",\n        amount_sol=0.1,\n    )\n\n    # ── Escrow ──────────────────────────────────────\n    escrow = await aw.escrow.create(\n        funder_wallet=wallets.data[0].id,\n        recipient_address=\"Worker...\",\n        amount_sol=2.0,\n        expires_in_hours=48,\n    )\n    await aw.escrow.release(escrow.id)\n\n    # ── PDA Wallets ─────────────────────────────────\n    pda = await aw.pda_wallets.create(\n        authority_wallet_id=wallets.data[0].id,\n        agent_id_seed=\"my-agent\",\n        spending_limit_per_tx=100_000_000,\n        daily_limit=500_000_000,\n    )\n    state = await aw.pda_wallets.get_state(pda.id)\n\n    # ── Policies ────────────────────────────────────\n    await aw.policies.create(\n        name=\"Daily Cap\",\n        rules={\"daily_limit_lamports\": 5_000_000_000},\n        scope_type=\"agent\",\n        scope_id=agent.id,\n    )\n\n    # ── Analytics ───────────────────────────────────\n    summary = await aw.analytics.summary()\n```\n\n---\n\n## Dashboard\n\nDark-themed React dashboard at `http://localhost:5173`.\n\n| Page | What You See |\n|---|---|\n| **Dashboard** | Stat cards, spend charts (Recharts), agent activity |\n| **Agents** | CRUD table, status, reputation scores |\n| **Wallets** | Addresses, balances, types, fund actions |\n| **Transactions** | Filterable TX history with status badges |\n| **Analytics** | Line charts, bar charts, spending breakdowns |\n| **Policies** | Accordion view, JSON rule editor |\n| **Audit Log** | Immutable event stream with filters |\n| **Billing** | Tier comparison, usage meters, Stripe portal |\n\n---\n\n## CLI\n\n```bash\npython -m agentwallet_cli status          # Overview\npython -m agentwallet_cli agents list     # List agents\npython -m agentwallet_cli agents create --name \"my-agent\"\npython -m agentwallet_cli wallets balance \u003cwallet-id\u003e\npython -m agentwallet_cli transactions list --limit 20\npython -m agentwallet_cli dashboard       # Live Rich terminal dashboard\n```\n\n---\n\n## Core Engine Details\n\n### Transaction Engine\n```\nIdempotency Check → Permission Engine (policies) → Fee Calculation\n→ Build TX → Sign → Submit to Solana → Confirm (polling w/ backoff)\n→ Audit Log + Webhooks\n```\n\n### Escrow Service\n```\nCREATED ──► FUNDED ──┬──► RELEASED  (delivery confirmed)\n                     ├──► REFUNDED  (arbiter/expiry)\n                     ├──► DISPUTED  (either party)\n                     └──► EXPIRED   (auto-refund)\n```\n\nOn-chain PDA holds the funds. No one can rug.\n\n### Security\n- Private keys encrypted at rest (Fernet / AWS KMS)\n- Private keys **never** exposed via API\n- JWT + API Key dual authentication\n- bcrypt password hashing (with special char requirement)\n- Account lockout (5 failures → 15 min lock)\n- Redis-backed rate limiting with in-memory fallback\n- Immutable audit log\n- HMAC-signed webhook deliveries\n- CORS + input validation on all endpoints\n- Idempotency keys prevent double-spend\n- Security audit: [SECURITY_AUDIT.md](SECURITY_AUDIT.md)\n\n---\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|---|:---:|---|---|\n| `DATABASE_URL` | Yes | -- | PostgreSQL connection string |\n| `REDIS_URL` | Yes | -- | Redis connection string |\n| `SOLANA_RPC_URL` | Yes | devnet | Solana RPC endpoint |\n| `ENCRYPTION_KEY` | Yes | -- | Fernet key for wallet encryption |\n| `JWT_SECRET_KEY` | Yes | -- | JWT signing secret |\n| `PLATFORM_WALLET_ADDRESS` | Yes | -- | Receives platform fees |\n| `STRIPE_SECRET_KEY` | No | -- | Stripe billing |\n| `AWS_KMS_KEY_ID` | No | -- | Production key encryption |\n| `LOG_LEVEL` | No | `INFO` | Logging verbosity |\n\nGenerate encryption key:\n```bash\npython -c \"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())\"\n```\n\n---\n\n## Tech Stack\n\n```\nBACKEND         FastAPI 0.115 · SQLAlchemy 2.0 · asyncpg · Alembic\nCACHE/QUEUE     Redis 7 · arq\nDATABASE        PostgreSQL 16\nBLOCKCHAIN      Solana · solders 0.27 · Anchor 0.30 (Rust)\nFRONTEND        React 18 · TypeScript 5.6 · Vite 6 · Tailwind 3.4 · Recharts\nAUTH            JWT (python-jose) · bcrypt · API Keys\nENCRYPTION      Fernet (dev) · AWS KMS (prod)\nBILLING         Stripe\nLOGGING         structlog (JSON)\nCONTAINERS      Docker Compose\nTESTING         pytest · pytest-asyncio · httpx (84 tests)\n```\n\n---\n\n## Development\n\n```bash\npip install -e \".[dev]\"\nuvicorn agentwallet.main:app --reload --port 8000\npytest packages/api/tests/ -v  # 84 tests\ncd packages/dashboard \u0026\u0026 npm install \u0026\u0026 npm run dev\ncd packages/programs/agentwallet \u0026\u0026 anchor build\nruff check packages/api/\n```\n\n---\n\n## 🙏 We Need Your Feedback\n\nAgentWallet is live on **Solana Devnet** right now. We need developers and AI agent builders to:\n\n1. **Try the API** — Register, create agents, make transfers\n2. **Build integrations** — Connect your AI agents to AgentWallet\n3. **Test the marketplace** — List services, hire agents, use escrow\n4. **Break things** — Find bugs, report edge cases\n5. **Tell us what's missing** — What features would make this 10x better?\n\n### Give Feedback:\n- **GitHub Issues:** [github.com/YouthAIAgent/agentwallet/issues](https://github.com/YouthAIAgent/agentwallet/issues)\n- **Twitter:** [@Web3__Youth](https://twitter.com/Web3__Youth)\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n```bash\ngit clone https://github.com/yourusername/agentwallet.git\ncd agentwallet\npip install -e \".[dev]\"\ndocker compose up -d postgres redis\nuvicorn agentwallet.main:app --reload\npytest packages/api/tests/ -v\n```\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n## Built by\n\n**[@Web3__Youth](https://twitter.com/Web3__Youth)** — Building autonomous financial infrastructure for the agentic economy.\n\n**Your agents don't need permission. They need a wallet.**\n\n🔗 **Website:** [agentwallet.fun](https://agentwallet.fun)\n🔗 **API:** [api.agentwallet.fun](https://api.agentwallet.fun)\n🔗 **GitHub:** [github.com/YouthAIAgent/agentwallet](https://github.com/YouthAIAgent/agentwallet)\n🔗 **SDK:** `pip install aw-protocol-sdk==0.3.0`\n🔗 **MCP:** `pip install agentwallet-mcp`\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eBuilt for the agentic economy.\u003c/strong\u003e\u003cbr\u003e\n  \u003csub\u003eEvery agent deserves a wallet. Every wallet deserves limits. Every transaction deserves a trail.\u003c/sub\u003e\n\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyouthaiagent%2Fagentwallet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyouthaiagent%2Fagentwallet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyouthaiagent%2Fagentwallet/lists"}