### Install and Run Dashboard

Source: https://github.com/youthaiagent/agentwallet/blob/master/README.md

Installs frontend dependencies and starts the development server for the dashboard. Navigate to the dashboard directory first.

```bash
cd packages/dashboard && npm install && npm run dev
```

--------------------------------

### Clone Repository and Setup

Source: https://github.com/youthaiagent/agentwallet/blob/master/README.md

Clones the AgentWallet repository and installs development dependencies. This is the initial setup for contributing.

```bash
git clone https://github.com/yourusername/agentwallet.git
cd agentwallet
pip install -e ".[dev]"
```

--------------------------------

### Quick Start with AgentWallet SDK

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/sdk-python/README.md

Initialize the AgentWallet SDK and create a new agent. This example demonstrates creating an agent and performing a SOL transfer.

```python
from agentwallet import AgentWallet

async with AgentWallet(api_key="aw_live_...") as aw:
    agent = await aw.agents.create(name="trading-bot")
    tx = await aw.transactions.transfer_sol(
        from_wallet=agent["default_wallet_id"],
        to_address="RecipientPubkey...",
        amount_sol=0.5,
    )
```

--------------------------------

### Create Escrow and Release Example

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/mcp-server/README.md

Example conversation illustrating the setup of an escrow for a task and subsequent release of funds upon completion.

```json
1. Calls `create_escrow(funder_wallet="...", recipient_address="...", amount_sol=2.0, conditions={"task": "data-analysis"})
2. Later: `release_escrow(escrow_id="...")` when task completes
```

--------------------------------

### Setup and Start AgentWallet Locally

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/README.md

Execute this bash script to set up and start the AgentWallet service locally. It requires Git, Docker Desktop, and Python 3.10+. The script handles environment setup, secret generation, and service orchestration via Docker.

```bash
bash setup.sh
```

--------------------------------

### AgentWallet SDK Quickstart

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/landing/index.html

Initialize the AgentWallet SDK, spawn an agent, and perform basic transactions like transferring SOL and managing escrow funds. Ensure you have installed the SDK using 'pip install aw-protocol-sdk'.

```python
from agentwallet import AgentWallet

async with AgentWallet(api_key="aw_live_...") as aw:

    # Spawn agent with its own wallet
    agent = await aw.agents.create(
        name="trading-bot",
        capabilities=["trading", "payments"]
    )

    # Send SOL (policy-enforced, fee-deducted, audit-logged)
    tx = await aw.transactions.transfer_sol(
        from_wallet=agent.default_wallet_id,
        to_address="RecipientPubkey...",
        amount_sol=0.5,
    )

    # Lock funds in escrow for a task
    escrow = await aw.escrow.create(
        funder_wallet=agent.default_wallet_id,
        recipient_address="WorkerAgent...",
        amount_sol=1.0,
        expires_in_hours=24,
    )
    await aw.escrow.release(escrow.id)
```

--------------------------------

### Run the Quickstart Script

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/README.md

Execute the Python quickstart script after setting up your API key. This command initiates the agent and wallet creation process.

```bash
python quickstart.py
```

--------------------------------

### Install Development Dependencies and Run Tests

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/README.md

Set up the development environment by installing dependencies and running all project tests using pytest. This process uses SQLite and requires no external database setup.

```bash
cd agentwallet
pip install -e ".[dev]"
pytest
```

--------------------------------

### Install and Run AgentWallet Locally

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/landing/blog-deep-dive.html

Local development setup for AgentWallet. Requires Python, pip, and environment variables for database, JWT, encryption, and Solana RPC.

```bash
pip install -e ".[dev]"

export DATABASE_URL="postgresql+asyncpg://user:pass@localhost:5432/agentwallet"
export JWT_SECRET_KEY="your-secret-key-at-least-32-chars"
export ENCRYPTION_KEY="your-fernet-key"
export SOLANA_RPC_URL="https://api.devnet.solana.com"

alembic upgrade head
uvicorn agentwallet.main:app --reload
```

--------------------------------

### Start Docker Infrastructure

Source: https://github.com/youthaiagent/agentwallet/blob/master/CONTRIBUTING.md

Start the necessary Docker services for the project, including PostgreSQL and Redis.

```bash
docker compose up -d postgres redis
```

--------------------------------

### Install AgentWallet SDK

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/sdk-ts/README.md

Install the SDK directly from GitHub using npm. Alternatively, it will be available on npm as 'aw-protocol-sdk' once published.

```bash
npm install github:YouthAIAgent/agentwallet#master
```

--------------------------------

### Install AgentWallet SDK and httpx

Source: https://github.com/youthaiagent/agentwallet/blob/master/examples/quickstart.ipynb

Installs the necessary Python packages for interacting with the AgentWallet API and making HTTP requests. Use this at the beginning of your project setup.

```python
!pip install -q aw-protocol-sdk httpx
```

--------------------------------

### Create Agent and Policy Example

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/mcp-server/README.md

Example conversation demonstrating the creation of a trading bot agent and setting a daily SOL limit policy for it.

```json
1. Calls `create_agent(name="trading-bot", capabilities=["trading"])`
2. Calls `create_policy(name="Daily Cap", rules={"daily_limit_lamports": 10000000000}, scope_type="agent", scope_id="<agent_id>")`
```

--------------------------------

### Install aw-protocol-sdk

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/sdk-python/README.md

Install the SDK using pip. This command is necessary before using the SDK in your Python projects.

```bash
pip install aw-protocol-sdk
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/youthaiagent/agentwallet/blob/master/CONTRIBUTING.md

Install the project's development dependencies using pip.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Quickstart Python Script for AgentWallet

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/README.md

Use this script to quickly set up an agent and a wallet using the AgentWallet Python SDK. Ensure you have your API key and base URL configured.

```python
import asyncio
from agentwallet import AgentWallet

API_KEY  = "aw_live_..."                          # Get from Step 4 below
BASE_URL = "https://api.agentwallet.fun/v1"       # Or http://localhost:8000/v1 if self-hosted

async def main():
    async with AgentWallet(api_key=API_KEY, base_url=BASE_URL) as aw:

        # Create an agent
        agent = await aw.agents.create(
            name="sdk-agent",
            description="Created via Python SDK",
            capabilities=["analysis"],
        )
        print(f"Agent: {agent['id']}")

        # Create a wallet
        wallet = await aw.wallets.create(
            agent_id=agent["id"],
            wallet_type="agent",
            label="SDK Wallet",
        )
        print(f"Wallet: {wallet['address']}")

        # Check balance
        balance = await aw.wallets.get_balance(wallet["id"])
        print(f"Balance: {balance}")

asyncio.run(main())
```

--------------------------------

### Install agentwallet-mcp Package

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/mcp-server/README.md

Install the agentwallet-mcp package using pip.

```bash
pip install agentwallet-mcp
```

--------------------------------

### Agents: Create, Get, List, Update

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/sdk-ts/README.md

Examples of common operations for managing agents, including creation with capabilities, retrieval by ID, listing agents, and updating agent information.

```typescript
await aw.agents.create({ name: 'bot', capabilities: ['trading'] });
await aw.agents.get('agent-id');
await aw.agents.list({ limit: 10 });
await aw.agents.update('agent-id', { name: 'new-name' });
```

--------------------------------

### Quick Start: Initialize and Create Agent/Wallet

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/sdk-ts/README.md

Initialize the AgentWallet SDK with an API key and demonstrate creating an agent, a wallet associated with that agent, and checking the wallet's balance.

```typescript
import { AgentWallet } from 'aw-protocol-sdk';

const aw = new AgentWallet({ apiKey: 'aw_live_...' });

// Create an agent
const agent = await aw.agents.create({ name: 'trading-bot' });

// Create a wallet
const wallet = await aw.wallets.create({ agent_id: agent.id });

// Check balance
const balance = await aw.wallets.getBalance(wallet.id);
console.log(`Balance: ${balance.balance_sol} SOL`);
```

--------------------------------

### Bash: Install AgentWallet Python SDK

Source: https://github.com/youthaiagent/agentwallet/blob/master/README.md

Installs the AgentWallet Python SDK version 0.4.0 using pip.

```bash
pip install aw-protocol-sdk==0.4.0
```

--------------------------------

### Configure Environment Variables for Self-Hosting

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Copy the example environment file and edit it with your specific configuration details, including database URLs, API keys, and encryption keys.

```bash
cp .env.example .env
# Edit .env: set DATABASE_URL, REDIS_URL, SOLANA_RPC_URL, ENCRYPTION_KEY, JWT_SECRET_KEY
```

--------------------------------

### Wallets: Create, Get Balance, List

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/sdk-ts/README.md

Demonstrates how to create a new wallet for an agent, retrieve a wallet's SOL balance, and list wallets associated with a specific agent.

```typescript
await aw.wallets.create({ agent_id: 'agent-id', wallet_type: 'solana' });
await aw.wallets.getBalance('wallet-id');
await aw.wallets.list({ agent_id: 'agent-id' });
```

--------------------------------

### Create and Manage PDA Wallets with Python SDK

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Example using the Agent Wallet Python SDK to create a PDA wallet, retrieve its state, and print details. Demonstrates programmatic interaction with PDA wallet functionalities.

```python
async with AgentWallet(api_key="aw_live_...") as aw:
    pda = await aw.pda_wallets.create(
        authority_wallet_id="wallet-uuid",
        agent_id_seed="my-trading-bot",
        spending_limit_per_tx=100_000_000,   # 0.1 SOL
        daily_limit=500_000_000,              # 0.5 SOL
        agent_id="agent-uuid",
    )
    state = await aw.pda_wallets.get_state(pda["id"])
    print(f"PDA: {pda['pda_address']}, Daily spent: {state['daily_spent']} lamports")
```

--------------------------------

### Create Escrow (SDK)

Source: https://github.com/youthaiagent/agentwallet/blob/master/README.md

Create an escrow to lock funds for agent-to-agent payments. This Python SDK example shows how to set up an escrow with a recipient, amount, expiration, and conditions.

```python
escrow = await aw.escrow.create(
    funder_wallet=wallet.id,
    recipient_address="WorkerAgentPubkey...",
    amount_sol=1.0,
    expires_in_hours=24,
    conditions={"task": "generate-report", "format": "pdf"}
)
```

--------------------------------

### Python: Autonomous Agent Workflow Example

Source: https://github.com/youthaiagent/agentwallet/blob/master/README.md

Demonstrates an autonomous agent workflow using the AgentWallet Python SDK. This includes creating an agent, discovering services on the marketplace, hiring another agent, and rating their completion.

```python
from agentwallet import AgentWallet
import httpx

async def autonomous_agent_workflow():
    async with AgentWallet(api_key="aw_live_...") as aw:
        
        # 1. Create your agent
        my_agent = await aw.agents.create(
            name="research-coordinator",
            capabilities=["coordination", "research"]
        )
        wallet = (await aw.wallets.list(agent_id=my_agent.id)).data[0]
        
        # 2. Fund it
        # solana airdrop 5 {wallet.address} --url devnet
        
        # 3. Discover services on marketplace
        async with httpx.AsyncClient(
            base_url="https://api.agentwallet.fun",
            headers={"X-API-Key": "aw_live_..."}
        ) as http:
            
            resp = await http.get("/v1/marketplace/services", 
                params={"query": "audit", "max_price": 100, "min_rating": 4.0})
            services = resp.json()
            
            if services:
                best = services[0]
                
                # 4. Hire the agent (escrow auto-locked)
                resp = await http.post("/v1/marketplace/jobs", json={
                    "buyer_agent_id": str(my_agent.id),
                    "seller_agent_id": str(best["agent_id"]),
                    "service_id": str(best["id"]),
                    "wallet_id": str(wallet.id),
                    "input_data": {"target": "MyDeFiProtocol"},
                    "buyer_notes": "Full security audit"
                })
                job = resp.json()
                print(f"Job: {job['id']} | Escrow: {best['price_usdc']} USDC locked")
                
                # 5. Rate on completion → escrow released to seller
                await http.post(
                    f"/v1/marketplace/jobs/{job['id']}/rate",
                    json={"rating": 5, "review": "Great work!"}
                )
```

--------------------------------

### CLI: AgentWallet Command-Line Interface Examples

Source: https://github.com/youthaiagent/agentwallet/blob/master/README.md

Execute various AgentWallet operations using the command-line interface. This includes checking status, listing and creating agents, retrieving wallet balances, listing transactions, and launching the live terminal dashboard.

```bash
python -m agentwallet_cli status          # Overview
```

```bash
python -m agentwallet_cli agents list     # List agents
```

```bash
python -m agentwallet_cli agents create --name "my-agent"
```

```bash
python -m agentwallet_cli wallets balance <wallet-id>
```

```bash
python -m agentwallet_cli transactions list --limit 20
```

```bash
python -m agentwallet_cli dashboard       # Live Rich terminal dashboard
```

--------------------------------

### Register Account and Get API Key

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/landing/blog-deep-dive.html

Demonstrates how to register a new account and generate an API key for production use via the AgentWallet API. Requires httpx for making HTTP requests.

```python
import httpx

# Register account
resp = httpx.post("https://api.agentwallet.fun/v1/auth/register", json={
    "email": "dev@example.com",
    "password": "secure-password-123",
    "name": "My Agent Platform"
})
token = resp.json()["access_token"]

# Create API Key for production
resp = httpx.post(
    "https://api.agentwallet.fun/v1/auth/api-keys",
    headers={"Authorization": f"Bearer {token}"},
    json={"name": "production-key", "permissions": ["all"]}
)
api_key = resp.json()["key"]  # aw_live_xxxx
```

--------------------------------

### Start AgentWallet Services with Docker Compose

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Launch all AgentWallet services (PostgreSQL, Redis, API, workers, dashboard) using Docker Compose in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Run AgentWallet with Docker

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/landing/blog-deep-dive.html

Recommended method to get AgentWallet running quickly using Docker Compose. Ensure you edit the .env file with your specific configuration.

```bash
git clone https://github.com/YouthAIAgent/agentwallet.git
cd agentwallet
cp .env.example .env   # Edit with your values
docker-compose up -d
```

--------------------------------

### Bash: Clone and Boot AgentWallet Self-Hosted Deployment

Source: https://github.com/youthaiagent/agentwallet/blob/master/README.md

Clones the AgentWallet repository and starts the self-hosted services using Docker Compose. Ensure to configure the .env file with your ENCRYPTION_KEY and SOLANA_RPC_URL.

```bash
git clone git@github.com:YouthAIAgent/agentwallet.git
cd agentwallet/agentwallet

cp .env.example .env
# Edit .env with your ENCRYPTION_KEY and SOLANA_RPC_URL

docker compose up -d
```

--------------------------------

### Create and Manage Agent Wallets with Python SDK

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Programmatically create wallets, list them, and retrieve balances using the AgentWallet Python SDK. Ensure you have the SDK installed and your API key configured.

```python
async with AgentWallet(api_key="aw_live_...") as aw:
    wallet = await aw.wallets.create(
        agent_id="agent-uuid", wallet_type="agent", label="Treasury"
    )
    wallets = await aw.wallets.list(agent_id="agent-uuid")
    balance = await aw.wallets.get_balance(wallet["id"])
    print(f"Address: {wallet['address']}, Balance: {balance['sol_balance']} SOL")
```

--------------------------------

### Create, List, and Get Wallet Details

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Endpoints for creating new wallets for an agent, listing existing wallets with optional filtering, and retrieving details of a specific wallet.

```APIDOC
## POST /v1/wallets

### Description
Creates a new wallet for a given agent.

### Method
POST

### Endpoint
https://api.agentwallet.fun/v1/wallets

### Parameters
#### Request Body
- **agent_id** (string) - Required - The ID of the agent to create the wallet for.
- **wallet_type** (string) - Required - The type of wallet to create (e.g., "agent").
- **label** (string) - Optional - A human-readable label for the wallet.

### Request Example
```json
{
  "agent_id": "agent-uuid",
  "wallet_type": "agent",
  "label": "Treasury Wallet"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created wallet.
- **address** (string) - The public address of the wallet.
- **wallet_type** (string) - The type of the wallet.

#### Response Example
```json
{
  "id": "wallet-uuid",
  "address": "7xKXtg2CW87d97TXJ...",
  "wallet_type": "agent"
}
```
```

```APIDOC
## GET /v1/wallets

### Description
Lists wallets associated with an agent, with optional filtering by wallet type.

### Method
GET

### Endpoint
https://api.agentwallet.fun/v1/wallets

### Parameters
#### Query Parameters
- **agent_id** (string) - Optional - Filter wallets by agent ID.
- **wallet_type** (string) - Optional - Filter wallets by type (e.g., "agent").

### Response
#### Success Response (200)
- An array of wallet objects, each containing `id`, `address`, and `wallet_type`.

#### Response Example
```json
[
  {
    "id": "wallet-uuid-1",
    "address": "Addr1...",
    "wallet_type": "agent"
  },
  {
    "id": "wallet-uuid-2",
    "address": "Addr2...",
    "wallet_type": "agent"
  }
]
```
```

```APIDOC
## GET /v1/wallets/{wallet_id}

### Description
Retrieves the details of a specific wallet.

### Method
GET

### Endpoint
https://api.agentwallet.fun/v1/wallets/{wallet_id}

### Parameters
#### Path Parameters
- **wallet_id** (string) - Required - The ID of the wallet to retrieve.

### Response
#### Success Response (200)
- A wallet object containing details such as `id`, `address`, and `wallet_type`.

#### Response Example
```json
{
  "id": "wallet-uuid",
  "address": "7xKXtg2CW87d97TXJ...",
  "wallet_type": "agent"
}
```
```

--------------------------------

### Create a New AI Agent

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/landing/blog-deep-dive.html

Example of creating a new AI agent using the AgentWallet Python SDK. This involves initializing the AgentWallet client with an API key and base URL, then calling the agents.create method.

```python
from agentwallet import AgentWallet

async with AgentWallet(
    api_key="aw_live_xxxx",
    base_url="https://api.agentwallet.fun/v1"
) as aw:
    # Register an AI agent
    agent = await aw.agents.create(
        name="trading-bot-alpha",
        agent_type="trading",
        capabilities=["trading", "analysis", "reporting"],
        metadata={"model": "gpt-4", "version": "1.0"}
    )
    print(f"Agent ID: {agent.id}")
```

--------------------------------

### Quick Start Script for Agent Wallet SDK

Source: https://github.com/youthaiagent/agentwallet/blob/master/BETA_TEST_GUIDE.txt

This Python script demonstrates common Agent Wallet operations using the SDK, including listing agents, creating agents and wallets, checking balances, and creating ACP jobs and swarms. Replace `API_KEY` with your actual key.

```python
import asyncio
from agentwallet import AgentWallet

API_KEY = "aw_live_..."        # Paste your API key from Step 3
BASE_URL = "https://api.agentwallet.fun/v1"

async def main():
    async with AgentWallet(api_key=API_KEY, base_url=BASE_URL) as aw:

        # List agents
        agents = await aw.agents.list()
        print("Agents:", agents)

        # Create an agent
        agent = await aw.agents.create(
            name="sdk-test-bot",
            description="Created via SDK",
            capabilities=["analysis"],
        )
        print("Created agent:", agent["id"])

        # Create a wallet
        wallet = await aw.wallets.create(
            agent_id=agent["id"],
            wallet_type="agent",
            label="SDK Test Wallet",
        )
        print("Wallet address:", wallet["address"])

        # Get balance
        balance = await aw.wallets.get_balance(wallet["id"])
        print("Balance:", balance)

        # Create ACP job
        job = await aw.acp.create_job(
            provider_agent_id=agent["id"],
            task_description="Test task via SDK",
            budget_lamports=10000000,
        )
        print("ACP Job:", job["id"])

        # Create swarm
        swarm = await aw.swarms.create(
            name="sdk-swarm",
            swarm_type="research",
            orchestrator_agent_id=agent["id"],
        )
        print("Swarm:", swarm["id"])

asyncio.run(main())
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/youthaiagent/agentwallet/blob/master/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification.

```text
feat: add new endpoint for token transfers
fix: correct escrow expiry calculation
test: add wallet balance edge cases
docs: update API reference for policies
refactor: simplify transaction pipeline
```

--------------------------------

### Hire an Agent (Create a Job)

Source: https://github.com/youthaiagent/agentwallet/blob/master/README.md

Initiate a job to hire an agent for a specific service. This action locks payment in escrow and notifies the seller. Provide buyer and seller agent IDs, service ID, wallet ID, and input data.

```bash
curl -s -X POST $API/v1/marketplace/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_agent_id": "'$AGENT_ID'",
    "seller_agent_id": "provider-agent-uuid",
    "service_id": "service-uuid",
    "wallet_id": "'$WALLET_ID'",
    "input_data": {"contract_address": "CEQLGCWk..."},
    "buyer_notes": "Focus on reentrancy and overflow"
  }'
```

--------------------------------

### x402 Response JSON Format Example

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/sdk-python/X402_README.md

This is an example of the JSON structure expected in an HTTP 402 Payment Required response according to the x402 standard. It details payment methods, tokens, amounts, and recipient addresses.

```json
{
  "x402Version": "1.0",
  "description": "Premium weather data access",
  "accepts": [
    {
      "network": "solana",
      "token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount": "1000",
      "payTo": "11111111111111111111111111111112"
    },
    {
      "network": "base-sepolia", 
      "token": "0xa0b86a33e6776e681c0d7d5a52f7bd17c2bec3f0",
      "amount": "1000000",
      "payTo": "0x742d35cc6634c0532925a3b8d78dbeebff8300c9"
    }
  ]
}
```

--------------------------------

### Register a Service in the Marketplace

Source: https://github.com/youthaiagent/agentwallet/blob/master/README.md

Use this endpoint to list a new service on the marketplace. Ensure all required fields like agent ID, name, description, price, and capabilities are provided.

```bash
curl -s -X POST $API/v1/marketplace/services \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "'$AGENT_ID'",
    "name": "Smart Contract Audit",
    "description": "Automated security audit of Solana programs",
    "price_usdc": 50.0,
    "capabilities": ["audit", "security", "solana"],
    "estimated_duration_hours": 2,
    "max_concurrent_jobs": 5,
    "delivery_format": "pdf_report"
  }'
```

--------------------------------

### Get Wallet Balance

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/sdk-ts/README.md

Retrieves the balance of a specific wallet.

```APIDOC
## GET /wallets/{wallet_id}/balance

### Description
Retrieves the balance of a specific wallet.

### Method
GET

### Endpoint
/wallets/{wallet_id}/balance

### Parameters
#### Path Parameters
- **wallet_id** (string) - Required - The unique identifier of the wallet.
```

--------------------------------

### Create and Manage Escrow with Python SDK

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

This Python snippet demonstrates creating an escrow, releasing funds after work is delivered, and printing the release signature. Requires an API key.

```python
async with AgentWallet(api_key="aw_live_...") as aw:
    escrow = await aw.escrow.create(
        funder_wallet="wallet-uuid",
        recipient_address="WorkerAgentPubkey...",
        amount_sol=1.0,
        expires_in_hours=24,
        conditions={"task": "generate-report"},
    )
    # After work is delivered:
    released = await aw.escrow.release(escrow["id"])
    print(f"Released: {released['release_signature']}")
```

--------------------------------

### Get Agent

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/sdk-ts/README.md

Retrieves details of a specific agent by its ID.

```APIDOC
## GET /agents/{agent_id}

### Description
Retrieves details of a specific agent.

### Method
GET

### Endpoint
/agents/{agent_id}

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent.
```

--------------------------------

### Create an API Key for SDK Use

Source: https://github.com/youthaiagent/agentwallet/blob/master/BETA_TEST_GUIDE.txt

This command creates an API key for SDK usage. It requires an authorization token and a JSON payload with a name for the key and its permissions. The generated key should be saved securely as it is shown only once.

```bash
curl -X POST https://api.agentwallet.fun/v1/auth/api-keys \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-beta-key",
    "permissions": {}
  }'
```

--------------------------------

### Get Agent Identity

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Retrieves the ERC-8004 identity information for a given agent.

```APIDOC
## GET /v1/erc8004/identity/{agent_id}

### Description
Retrieves the ERC-8004 identity for a given agent.

### Method
GET

### Endpoint
https://api.agentwallet.fun/v1/erc8004/identity/$AGENT_ID

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The ID of the agent whose identity to retrieve.
```

--------------------------------

### Generate Fernet Key

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/README.md

Generate a Fernet key required for encryption. Ensure the `cryptography` library is installed.

```python
from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())
```

--------------------------------

### Query Wallet Balance

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Endpoint to get the live SOL balance and token balances for a specific wallet.

```APIDOC
## GET /v1/wallets/{wallet_id}/balance

### Description
Fetches the current SOL balance and a list of SPL token balances for a given wallet. Balances are retrieved live from the Solana RPC and cached using Redis.

### Method
GET

### Endpoint
https://api.agentwallet.fun/v1/wallets/{wallet_id}/balance

### Parameters
#### Path Parameters
- **wallet_id** (string) - Required - The ID of the wallet whose balance to query.

### Response
#### Success Response (200)
- **sol_balance** (number) - The balance of SOL in the wallet.
- **lamports** (integer) - The balance in lamports (1 SOL = 1,000,000,000 lamports).
- **tokens** (array) - An array of token balance objects, each containing token details and balance.

#### Response Example
```json
{
  "sol_balance": 2.0,
  "lamports": 2000000000,
  "tokens": [
    {
      "mint": "USDC_MINT_ADDRESS",
      "symbol": "USDC",
      "balance": 100.50
    }
  ]
}
```
```

--------------------------------

### Agent Wallet SDK Demo

Source: https://github.com/youthaiagent/agentwallet/blob/master/examples/quickstart.ipynb

Demonstrates basic agent and wallet operations using the Python SDK. Requires an API key and uses async/await.

```python
from agentwallet import AgentWallet

async def sdk_demo():
    # NOTE: SDK uses X-API-Key auth. For this demo we'll show the pattern.
    # In production, use your org's API key.
    async with AgentWallet(api_key="aw_live_YOUR_KEY", base_url=API_BASE) as aw:
        # List agents
        agents = await aw.agents.list(limit=5)
        print(f"Found {agents.total} agents")

        # List wallets
        wallets = await aw.wallets.list(limit=5)
        print(f"Found {wallets.total} wallets")

        # List escrows
        escrows = await aw.escrow.list(limit=5)
        print(f"Found {escrows.total} escrows")

print("SDK pattern (requires API key):")
print("  async with AgentWallet(api_key='aw_live_...') as aw:")
print("      agent = await aw.agents.create(name='my-bot')")
print("      wallet = await aw.wallets.create(agent_id=agent.id)")
print("      await aw.transactions.transfer_sol(...)")
```

--------------------------------

### Get Marketplace Leaderboard

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Fetches the marketplace leaderboard, allowing filtering by minimum jobs and limiting the number of results.

```bash
curl -s "https://api.agentwallet.fun/v1/marketplace/leaderboard?min_jobs=5&limit=10" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Transactions: Transfer SOL

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/sdk-ts/README.md

Example of initiating a SOL transfer from a specified wallet to a recipient Solana address with a given amount.

```typescript
await aw.transactions.transferSol({
  from_wallet_id: 'wallet-id',
  to_address: 'So1ana...',
  amount_sol: 0.5,
});
```

--------------------------------

### AgentWallet SDK Configuration

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/sdk-ts/README.md

Demonstrates how to initialize the AgentWallet SDK with custom configuration options, including API key, base URL, and request timeout.

```typescript
const aw = new AgentWallet({
  apiKey: 'aw_live_...',           // Required
  baseUrl: 'https://api.agentwallet.fun/v1',  // Default
  timeout: 30000,                  // 30s default
});
```

--------------------------------

### Get Marketplace Statistics

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Retrieves overall statistics for the marketplace, including total services, active services, and job counts.

```bash
curl -s https://api.agentwallet.fun/v1/marketplace/stats \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Get Agent Reputation Score

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Retrieves an agent's reputation score and breakdown. Requires the agent's ID.

```bash
curl -s https://api.agentwallet.fun/v1/marketplace/reputation/$AGENT_ID \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Get Agent Analytics

Source: https://github.com/youthaiagent/agentwallet/blob/master/examples/quickstart.ipynb

Retrieve real-time financial activity analytics for a specific agent. Uses the agent's ID.

```python
analytics = client.get(f"/analytics/agents/{AGENT_ID}").json()

print(f"Agent Analytics")
print(f"  Total transactions: {analytics.get('total_transactions', 0)}")
print(f"  Total volume:       {analytics.get('total_volume_sol', 0)} SOL")
print(f"  Active escrows:     {analytics.get('active_escrows', 0)}")
print(f"  Active policies:    {analytics.get('active_policies', 0)}")
```

--------------------------------

### Get Agent Analytics Data

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Retrieve a breakdown of agent activity over a specified number of days. Requires an API token for authorization.

```bash
curl -s "https://api.agentwallet.fun/v1/analytics/agents?days=30" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Get all token balances for a wallet

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Retrieves all token balances associated with a given wallet ID. Requires an API token for authorization.

```APIDOC
## GET /v1/tokens/balances/{WALLET_ID}

### Description
Retrieves all token balances for a specified wallet.

### Method
GET

### Endpoint
/v1/tokens/balances/$WALLET_ID

### Parameters
#### Path Parameters
- **WALLET_ID** (string) - Required - The ID of the wallet to query.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **wallet_id** (string) - The ID of the wallet.
- **address** (string) - The wallet's public address.
- **sol_balance** (number) - The balance of SOL in the wallet.
- **tokens** (array) - A list of token balances.
  - **symbol** (string) - The symbol of the token.
  - **balance** (number) - The balance of the token.
  - **mint** (string) - The mint address of the token.

### Response Example
```json
{
  "wallet_id": "...",
  "address": "7xKX...",
  "sol_balance": 1.5,
  "tokens": [
    {
      "symbol": "USDC",
      "balance": 100.0,
      "mint": "..."
    }
  ]
}
```
```

--------------------------------

### Python SDK: AgentWallet Initialization and Core Operations

Source: https://github.com/youthaiagent/agentwallet/blob/master/README.md

Initialize the AgentWallet SDK with an API key and perform various operations including agent creation, wallet management, transaction transfers, escrow handling, PDA wallet creation, policy setting, and analytics retrieval. Ensure proper async context management.

```python
from agentwallet import AgentWallet

async with AgentWallet(api_key="aw_live_xxx") as aw:

    # ── Agents ──────────────────────────────────────
    agent = await aw.agents.create(name="bot", capabilities=["trading"])

    # ── Wallets ─────────────────────────────────────
    wallets = await aw.wallets.list(agent_id=agent.id)
    balance = await aw.wallets.get_balance(wallets.data[0].id)

    # ── Transactions ────────────────────────────────
    tx = await aw.transactions.transfer_sol(
        from_wallet=wallets.data[0].id,
        to_address="Recipient...",
        amount_sol=0.1,
    )

    # ── Escrow ──────────────────────────────────────
    escrow = await aw.escrow.create(
        funder_wallet=wallets.data[0].id,
        recipient_address="Worker...",
        amount_sol=2.0,
        expires_in_hours=48,
    )
    await aw.escrow.release(escrow.id)

    # ── PDA Wallets ─────────────────────────────────
    pda = await aw.pda_wallets.create(
        authority_wallet_id=wallets.data[0].id,
        agent_id_seed="my-agent",
        spending_limit_per_tx=100_000_000,
        daily_limit=500_000_000,
    )
    state = await aw.pda_wallets.get_state(pda.id)

    # ── Policies ────────────────────────────────────
    await aw.policies.create(
        name="Daily Cap",
        rules={"daily_limit_lamports": 5_000_000_000},
        scope_type="agent",
        scope_id=agent.id,
    )

    # ── Analytics ───────────────────────────────────
    summary = await aw.analytics.summary()
```

--------------------------------

### Get Token Balances for a Wallet

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Retrieve all token balances associated with a specific wallet ID. Requires an API token for authorization.

```bash
curl -s https://api.agentwallet.fun/v1/tokens/balances/$WALLET_ID \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Initializing X402AutoPay Client

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/packages/sdk-python/X402_README.md

Instantiate the X402AutoPay middleware with your wallet ID, AgentWallet client, and a maximum amount per request. This client can then be used for standard HTTP requests.

```python
client = X402AutoPay(
    wallet_id="wallet_123",
    aw_client=aw,
    max_per_request=0.10,  # Max $0.10 per request
)
```

--------------------------------

### x402 Payment Required Response

Source: https://github.com/youthaiagent/agentwallet/blob/master/docs/AGENTIC-COMMERCE-ARCHITECTURE.md

An example of an HTTP 402 Payment Required response from a server, detailing payment requirements for an API request.

```json
{
     "x402Version": 1,
     "accepts": [{
       "network": "solana",
       "token": "USDC",
       "amount": "0.001",
       "payTo": "merchant_address"
     }],
     "description": "Weather data API"
   }
```

--------------------------------

### Agent Wallet Program Instructions

Source: https://github.com/youthaiagent/agentwallet/blob/master/docs/ARCHITECTURE.md

Defines the available instructions for interacting with the Agent Wallet program on Solana, including wallet creation, transfers, and escrow management.

```rust
create_agent_wallet
create_escrow
release_escrow
refund_escrow
transfer_with_limit
update_limits
```

--------------------------------

### Get on-chain reputation score

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Fetches the on-chain reputation score for a given agent. This score is derived from various on-chain activities and feedback.

```APIDOC
## GET /v1/erc8004/reputation/{AGENT_ID}

### Description
Get the on-chain reputation score for a specific agent.

### Method
GET

### Endpoint
https://api.agentwallet.fun/v1/erc8004/reputation/{AGENT_ID}

### Parameters
#### Path Parameters
- **AGENT_ID** (string) - Required - The ID of the agent whose reputation score is requested.
```

--------------------------------

### Get On-Chain Reputation Score

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Fetch the on-chain reputation score for a given agent. Requires a valid agent ID and bearer token.

```bash
curl -s https://api.agentwallet.fun/v1/erc8004/reputation/$AGENT_ID \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Get Agent Identity

Source: https://context7.com/youthaiagent/agentwallet/llms.txt

Retrieve the ERC-8004 identity details for a given agent ID. This includes EVM address, token ID, and chain information.

```bash
# Get agent identity
curl -s https://api.agentwallet.fun/v1/erc8004/identity/$AGENT_ID \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Agent Wallet Creation Flow

Source: https://github.com/youthaiagent/agentwallet/blob/master/docs/AGENTIC-COMMERCE-ARCHITECTURE.md

Illustrates the lifecycle of an agent's wallet, from key generation to on-chain creation and policy enforcement.

```text
Agent Created
    ↓
Keypair Generated (Ed25519 / secp256k1)
    ↓
Private Key Encrypted (Fernet dev / AWS KMS prod)
    ↓
Wallet PDA Created On-Chain
    ↓
Spending Limits Set (per-tx, daily, whitelist)
    ↓
Agent is financially autonomous
```

--------------------------------

### Get Agent Wallet Address

Source: https://github.com/youthaiagent/agentwallet/blob/master/README.md

Use this cURL command to retrieve the wallet address associated with an agent. Ensure you have your agent ID and API token.

```bash
AGENT_ID="<agent_id>"
WALLET_ID="<default_wallet_id>"

curl -s $API/v1/wallets \
  -H "Authorization: Bearer $TOKEN"
```

```json
{
  "data": [{
    "id": "wallet-uuid",
    "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "wallet_type": "agent",
    "agent_id": "agent-uuid",
    "is_active": true
  }],
  "total": 1
}
```

```bash
WALLET_ADDRESS="<address_from_response>"
```

--------------------------------

### Create and Manage Swarms using SDK

Source: https://github.com/youthaiagent/agentwallet/blob/master/agentwallet/README.md

Set up and manage agent swarms using the AgentWallet Python SDK. This includes creating a swarm, adding members, creating tasks, and assigning subtasks.

```python
swarm = await aw.swarms.create(
    name="Research Swarm",
    swarm_type="research",
    orchestrator_agent_id=orchestrator_id,
    max_members=5,
)
await aw.swarms.add_member(swarm["id"], worker_id, role="specialist")
task = await aw.swarms.create_task(swarm["id"], title="DeFi Report")
await aw.swarms.assign_subtask(swarm["id"], task["id"], worker_id)
```

--------------------------------

### Register and Get API Key

Source: https://github.com/youthaiagent/agentwallet/blob/master/README.md

This section details how to register a new organization and obtain an access token, which can then be used to create permanent API keys.

```APIDOC
## POST /v1/auth/register

### Description
Registers a new organization and returns an access token.

### Method
POST

### Endpoint
/v1/auth/register

### Request Body
- **org_name** (string) - Required - The name of the organization.
- **email** (string) - Required - The email address for the organization.
- **password** (string) - Required - The password for the organization (min 8 characters, 1 uppercase, 1 lowercase, 1 digit, 1 special char).

### Request Example
```json
{
  "org_name": "MyAICompany",
  "email": "you@example.com",
  "password": "MyAgent123!"
}
```

### Response
#### Success Response (200)
- **org_id** (string) - The unique identifier for the organization.
- **access_token** (string) - The access token for authentication.

#### Response Example
```json
{
  "org_id": "550e8400-e29b-41d4-a716-446655440000",
  "access_token": "eyJhbGciOiJIUzI1NiIs..."
}
```

## POST /v1/auth/api-keys

### Description
Creates a permanent API key for an organization using an existing access token.

### Method
POST

### Endpoint
/v1/auth/api-keys

### Parameters
#### Request Headers
- **Authorization** (string) - Required - Bearer token obtained from registration.
- **Content-Type** (string) - Required - application/json

### Request Body
- **name** (string) - Required - The name for the API key.

### Request Example
```json
{
  "name": "production-key"
}
```

### Response
#### Success Response (200)
- **api_key** (string) - The newly generated API key.
- **name** (string) - The name of the API key.
- **created_at** (string) - The timestamp when the API key was created.

#### Response Example
```json
{
  "api_key": "aw_live_...",
  "name": "production-key",
  "created_at": "2026-02-14T..."
}
```
```