{
  "openapi": "3.1.0",
  "info": {
    "title": "AgentWallex API",
    "description": "REST API for managing AI agent wallets, on-chain transactions, spending policies, webhooks, and x402 micropayments.",
    "version": "1.0.0",
    "contact": {
      "name": "AgentWallex Support",
      "url": "https://agentwallex.com"
    }
  },
  "servers": [
    {
      "url": "https://api.agentwallex.com",
      "description": "Production"
    },
    {
      "url": "https://api-sandbox.agentwallex.com",
      "description": "Sandbox"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Agents",
      "description": "Create and manage AI agent wallets."
    },
    {
      "name": "Transactions",
      "description": "Send payments and query transaction history."
    },
    {
      "name": "Policies",
      "description": "Configure spending limits and access controls."
    },
    {
      "name": "Webhooks",
      "description": "Register and manage webhook endpoints."
    },
    {
      "name": "x402",
      "description": "x402 micropayment negotiation and session management."
    }
  ],
  "paths": {
    "/api/v1/agents": {
      "post": {
        "operationId": "createAgent",
        "summary": "Create Agent",
        "description": "Create a new agent with an automatically provisioned MPC-secured wallet. The wallet address is generated using Distributed Key Generation (DKG) and is ready to receive funds immediately.",
        "tags": ["Agents"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_name", "chain"],
                "properties": {
                  "agent_name": {
                    "type": "string",
                    "description": "Display name for the agent. Must be unique within your account."
                  },
                  "agent_description": {
                    "type": "string",
                    "description": "Optional description of the agent's purpose."
                  },
                  "chain": {
                    "type": "string",
                    "description": "CAIP-2 chain identifier for the agent's wallet (e.g., `eip155:1` for Ethereum, `eip155:8453` for Base, `eip155:84532` for Base Sepolia testnet)."
                  },
                  "metadata": {
                    "type": "string",
                    "description": "JSON-encoded metadata string for custom key-value pairs."
                  }
                }
              },
              "example": {
                "agent_name": "research-bot",
                "agent_description": "Market research automation agent",
                "chain": "eip155:84532",
                "metadata": "{\"team\":\"growth\"}"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Agent"
                },
                "example": {
                  "id": "agent_abc123",
                  "agent_name": "research-bot",
                  "agent_description": "Market research automation agent",
                  "wallet": {
                    "address": "0x1234567890abcdef1234567890abcdef12345678",
                    "chain": "eip155:84532"
                  },
                  "status": "active",
                  "created_at": "2025-06-01T10:00:00Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "get": {
        "operationId": "listAgents",
        "summary": "List Agents",
        "description": "Retrieve a paginated list of agents associated with your account. Supports filtering by status and chain.",
        "tags": ["Agents"],
        "parameters": [
          {
            "$ref": "#/components/parameters/PageNum"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by agent status.",
            "schema": {
              "type": "string",
              "enum": ["active", "inactive"]
            }
          },
          {
            "name": "chain",
            "in": "query",
            "description": "Filter by CAIP-2 chain identifier (e.g., `eip155:84532`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of agents.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Agent"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/agents/{id}": {
      "get": {
        "operationId": "getAgent",
        "summary": "Get Agent",
        "description": "Retrieve the full details of a single agent, including wallet address, status, metadata, and creation timestamp.",
        "tags": ["Agents"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The unique agent identifier (e.g., `agent_abc123`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Agent details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Agent"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/transactions": {
      "post": {
        "operationId": "createTransaction",
        "summary": "Create Transaction",
        "description": "Submit a new transaction through an agent's wallet. The transaction passes through the policy engine for validation, then is signed via MPC and broadcast to the blockchain.",
        "tags": ["Transactions"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id", "direction", "type", "to_address", "amount", "token", "chain"],
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "description": "The agent whose wallet will send the transaction."
                  },
                  "direction": {
                    "type": "string",
                    "enum": ["outbound"],
                    "description": "Transaction direction. Currently only `outbound` is supported."
                  },
                  "type": {
                    "type": "string",
                    "enum": ["transfer"],
                    "description": "Transaction type."
                  },
                  "from_address": {
                    "type": "string",
                    "description": "Sender address. If omitted, the agent's wallet address is used."
                  },
                  "to_address": {
                    "type": "string",
                    "description": "Recipient on-chain address."
                  },
                  "amount": {
                    "type": "string",
                    "description": "Amount to send as a decimal string (e.g., `\"10.5\"`)."
                  },
                  "token": {
                    "type": "string",
                    "description": "Token symbol (e.g., `USDC`, `USDT`, `ETH`)."
                  },
                  "chain": {
                    "type": "string",
                    "description": "CAIP-2 chain identifier (e.g., `eip155:84532`)."
                  },
                  "memo": {
                    "type": "string",
                    "description": "Optional memo or reference string."
                  }
                }
              },
              "example": {
                "agent_id": "agent_abc123",
                "direction": "outbound",
                "type": "transfer",
                "to_address": "0xabcdef1234567890abcdef1234567890abcdef12",
                "amount": "10.5",
                "token": "USDC",
                "chain": "eip155:84532",
                "memo": "service payment"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transaction created and submitted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Transaction"
                },
                "example": {
                  "id": "tx_xyz789",
                  "hash": "0xabc123def456...",
                  "status": "confirmed",
                  "amount": "10.5",
                  "token": "USDC",
                  "fee": "0.001",
                  "created_at": "2025-06-15T14:30:00Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "get": {
        "operationId": "listTransactions",
        "summary": "List Transactions",
        "description": "List transactions across your account or filtered by agent and status.",
        "tags": ["Transactions"],
        "parameters": [
          {
            "$ref": "#/components/parameters/PageNum"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "name": "agent_id",
            "in": "query",
            "description": "Filter by agent ID.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by transaction status.",
            "schema": {
              "type": "string",
              "enum": ["pending", "confirmed", "failed"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of transactions.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Transaction"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/transactions/{id}": {
      "get": {
        "operationId": "getTransaction",
        "summary": "Get Transaction",
        "description": "Retrieve the full details of a single transaction, including on-chain hash, amount, token, fees, and current status.",
        "tags": ["Transactions"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The unique transaction identifier (e.g., `tx_xyz789`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transaction details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Transaction"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/policies": {
      "post": {
        "operationId": "createPolicy",
        "summary": "Create Policy",
        "description": "Create a new policy and attach it to an agent. Policies control what transactions an agent is allowed to execute. Every transaction is evaluated against the agent's policies before MPC signing.",
        "tags": ["Policies"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id", "type", "rules"],
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "description": "Agent to attach this policy to."
                  },
                  "type": {
                    "type": "string",
                    "enum": ["spending_limit", "address_control", "token_control", "velocity_control", "schedule", "human_approval"],
                    "description": "Policy type."
                  },
                  "rules": {
                    "$ref": "#/components/schemas/PolicyRules"
                  }
                }
              },
              "example": {
                "agent_id": "agent_abc123",
                "type": "spending_limit",
                "rules": {
                  "max_transaction_amount": "500",
                  "daily_limit": "5000",
                  "monthly_limit": "50000"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Policy created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Policy"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "get": {
        "operationId": "listPolicies",
        "summary": "List Policies",
        "description": "Retrieve all policies, optionally filtered by agent.",
        "tags": ["Policies"],
        "parameters": [
          {
            "$ref": "#/components/parameters/PageNum"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "name": "agent_id",
            "in": "query",
            "description": "Filter by agent ID.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of policies.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Policy"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/policies/{id}": {
      "get": {
        "operationId": "getPolicy",
        "summary": "Get Policy",
        "description": "Retrieve a single policy by ID.",
        "tags": ["Policies"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The policy ID (e.g., `pol_abc123`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Policy details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Policy"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "put": {
        "operationId": "updatePolicy",
        "summary": "Update Policy",
        "description": "Update an existing policy's rules.",
        "tags": ["Policies"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The policy ID to update (e.g., `pol_abc123`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["rules"],
                "properties": {
                  "rules": {
                    "$ref": "#/components/schemas/PolicyRules"
                  }
                }
              },
              "example": {
                "rules": {
                  "max_transaction_amount": "1000",
                  "daily_limit": "10000"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Policy updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Policy"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "delete": {
        "operationId": "deletePolicy",
        "summary": "Delete Policy",
        "description": "Remove a policy from an agent. Deleting a policy removes the constraint immediately.",
        "tags": ["Policies"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The policy ID to delete (e.g., `pol_abc123`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Policy deleted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The deleted policy ID."
                    },
                    "deleted": {
                      "type": "boolean",
                      "description": "Confirmation of deletion."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/webhooks": {
      "post": {
        "operationId": "createWebhook",
        "summary": "Create Webhook",
        "description": "Register a new webhook endpoint to receive real-time event notifications via HTTP POST.",
        "tags": ["Webhooks"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url", "events", "secret"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The HTTPS URL that will receive webhook events."
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of event types to subscribe to (e.g., `payment.completed`, `payment.failed`, `policy.violated`)."
                  },
                  "secret": {
                    "type": "string",
                    "description": "Signing secret used to verify webhook payloads. Must start with `whsec_`."
                  }
                }
              },
              "example": {
                "url": "https://your-app.com/webhooks/agentwallex",
                "events": ["payment.completed", "payment.failed", "policy.violated"],
                "secret": "whsec_your_signing_secret"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Webhook"
                },
                "example": {
                  "id": "whk_abc123",
                  "url": "https://your-app.com/webhooks/agentwallex",
                  "events": ["payment.completed", "payment.failed", "policy.violated"],
                  "status": "active",
                  "created_at": "2025-06-01T10:00:00Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "get": {
        "operationId": "listWebhooks",
        "summary": "List Webhooks",
        "description": "List all registered webhook endpoints.",
        "tags": ["Webhooks"],
        "parameters": [
          {
            "$ref": "#/components/parameters/PageNum"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of webhooks.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Webhook"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/webhooks/{id}": {
      "get": {
        "operationId": "getWebhook",
        "summary": "Get Webhook",
        "description": "Retrieve a single webhook endpoint by ID.",
        "tags": ["Webhooks"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook ID (e.g., `whk_abc123`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Webhook"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "put": {
        "operationId": "updateWebhook",
        "summary": "Update Webhook",
        "description": "Update a webhook's URL, events, or secret.",
        "tags": ["Webhooks"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook ID to update (e.g., `whk_abc123`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Updated HTTPS URL for the webhook endpoint."
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Updated list of event types to subscribe to."
                  },
                  "secret": {
                    "type": "string",
                    "description": "Updated signing secret. Must start with `whsec_`."
                  }
                }
              },
              "example": {
                "events": ["payment.completed", "payment.failed", "policy.violated", "agent.frozen"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Webhook"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "delete": {
        "operationId": "deleteWebhook",
        "summary": "Delete Webhook",
        "description": "Remove a webhook endpoint. No further events will be delivered.",
        "tags": ["Webhooks"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook ID to delete (e.g., `whk_abc123`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook deleted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The deleted webhook ID."
                    },
                    "deleted": {
                      "type": "boolean",
                      "description": "Confirmation of deletion."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/webhooks/{id}/test": {
      "post": {
        "operationId": "testWebhook",
        "summary": "Test Webhook",
        "description": "Send a test event to a webhook endpoint to verify your handler is working correctly.",
        "tags": ["Webhooks"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook ID to test (e.g., `whk_abc123`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Test event sent successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "description": "Whether the test event was delivered successfully."
                    },
                    "status_code": {
                      "type": "integer",
                      "description": "HTTP status code returned by the webhook endpoint."
                    },
                    "response_time_ms": {
                      "type": "integer",
                      "description": "Response time from the webhook endpoint in milliseconds."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/x402/pay": {
      "post": {
        "operationId": "x402Pay",
        "summary": "x402 Pay",
        "description": "Negotiate and complete one x402 payment for a target URL. AgentWallex evaluates the agent's policies, signs the payment via MPC, and returns the payment info needed to access the paid resource.",
        "tags": ["x402"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id", "target_url"],
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "description": "The agent whose wallet will fund the payment."
                  },
                  "target_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The x402-enabled URL to pay for (e.g., `https://paid-api.example.com/v1/data`)."
                  },
                  "session_id": {
                    "type": "string",
                    "description": "Optional session ID to deduct from an existing session budget."
                  },
                  "chain": {
                    "type": "string",
                    "description": "CAIP-2 chain identifier for payment settlement (e.g., `eip155:84532`). If omitted, the agent's default chain is used."
                  }
                }
              },
              "example": {
                "agent_id": "agent_abc123",
                "target_url": "https://paid-api.example.com/v1/data",
                "session_id": "sess_xyz789",
                "chain": "eip155:84532"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment completed successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/X402PayResult"
                },
                "example": {
                  "ledger_id": "ldg_abc123",
                  "amount": "0.10",
                  "fee_amount": "0.002",
                  "fee_rate": "2.0",
                  "token": "USDC",
                  "chain": "eip155:84532",
                  "status": "completed",
                  "payment_signature": "base64_encoded_signature..."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/x402/sessions": {
      "post": {
        "operationId": "createX402Session",
        "summary": "Create x402 Session",
        "description": "Create a new x402 payment session with a spending budget. Sessions let you pre-authorize a spending budget for repeated x402 API calls. Payments within a session are deducted from the session budget without requiring individual approval for each call.",
        "tags": ["x402"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id", "budget_limit", "chain", "ttl_seconds"],
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "description": "The agent whose wallet funds the session."
                  },
                  "budget_limit": {
                    "type": "string",
                    "description": "Maximum total amount the session can spend (e.g., `\"100.00\"`)."
                  },
                  "chain": {
                    "type": "string",
                    "description": "CAIP-2 chain identifier for settlement (e.g., `eip155:84532`)."
                  },
                  "ttl_seconds": {
                    "type": "integer",
                    "description": "Session time-to-live in seconds. The session expires after this duration."
                  },
                  "allowed_urls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    },
                    "description": "Optional list of URLs this session is authorized to pay. If omitted, all x402-enabled URLs are allowed."
                  }
                }
              },
              "example": {
                "agent_id": "agent_abc123",
                "budget_limit": "100.00",
                "chain": "eip155:84532",
                "ttl_seconds": 3600,
                "allowed_urls": ["https://paid-api.example.com/v1/data"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/X402Session"
                },
                "example": {
                  "id": "sess_xyz789",
                  "agent_id": "agent_abc123",
                  "budget_limit": "100.00",
                  "budget_spent": "0.00",
                  "budget_remaining": "100.00",
                  "chain": "eip155:84532",
                  "status": "active",
                  "expires_at": "2025-06-15T15:30:00Z",
                  "created_at": "2025-06-15T14:30:00Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "get": {
        "operationId": "listX402Sessions",
        "summary": "List x402 Sessions",
        "description": "List all x402 sessions for your account.",
        "tags": ["x402"],
        "parameters": [
          {
            "$ref": "#/components/parameters/PageNum"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of x402 sessions.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/X402Session"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/x402/sessions/{id}": {
      "get": {
        "operationId": "getX402Session",
        "summary": "Get x402 Session",
        "description": "Retrieve a single session including current budget status.",
        "tags": ["x402"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The session ID (e.g., `sess_xyz789`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Session details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/X402Session"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "delete": {
        "operationId": "deleteX402Session",
        "summary": "Delete x402 Session",
        "description": "Terminate a session and release any remaining budget. Deleting a session does not refund already-spent amounts. Only the unspent budget is released back to the agent's balance.",
        "tags": ["x402"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The session ID to delete (e.g., `sess_xyz789`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Session deleted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The deleted session ID."
                    },
                    "deleted": {
                      "type": "boolean",
                      "description": "Confirmation of deletion."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/x402/sessions/{id}/pay": {
      "post": {
        "operationId": "x402SessionPay",
        "summary": "Pay with x402 Session",
        "description": "Make a payment using an existing session budget.",
        "tags": ["x402"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The session ID to pay from (e.g., `sess_xyz789`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["target_url"],
                "properties": {
                  "target_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The x402-enabled URL to pay for."
                  }
                }
              },
              "example": {
                "target_url": "https://paid-api.example.com/v1/data"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session payment completed successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/X402PayResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key authentication. Keys are prefixed with `awx_`."
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JWT bearer token authentication."
      }
    },
    "parameters": {
      "PageNum": {
        "name": "page_num",
        "in": "query",
        "description": "Page number (1-indexed).",
        "schema": {
          "type": "integer",
          "default": 1,
          "minimum": 1
        }
      },
      "PageSize": {
        "name": "page_size",
        "in": "query",
        "description": "Number of items per page.",
        "schema": {
          "type": "integer",
          "default": 20,
          "minimum": 1,
          "maximum": 100
        }
      }
    },
    "schemas": {
      "Agent": {
        "type": "object",
        "description": "An AI agent with an MPC-secured wallet.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique agent identifier (e.g., `agent_abc123`)."
          },
          "agent_name": {
            "type": "string",
            "description": "Agent display name."
          },
          "agent_description": {
            "type": "string",
            "description": "Agent description."
          },
          "wallet": {
            "$ref": "#/components/schemas/Wallet"
          },
          "status": {
            "type": "string",
            "enum": ["active", "inactive"],
            "description": "Agent status."
          },
          "metadata": {
            "type": "string",
            "description": "JSON-encoded metadata string."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 creation timestamp."
          }
        }
      },
      "Wallet": {
        "type": "object",
        "description": "An on-chain wallet associated with an agent.",
        "properties": {
          "address": {
            "type": "string",
            "description": "On-chain wallet address."
          },
          "chain": {
            "type": "string",
            "description": "CAIP-2 chain identifier."
          }
        }
      },
      "Transaction": {
        "type": "object",
        "description": "An on-chain transaction submitted through an agent's wallet.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique transaction identifier."
          },
          "hash": {
            "type": "string",
            "description": "On-chain transaction hash (available after broadcast)."
          },
          "agent_id": {
            "type": "string",
            "description": "Agent that initiated the transaction."
          },
          "direction": {
            "type": "string",
            "enum": ["outbound"],
            "description": "Transaction direction."
          },
          "type": {
            "type": "string",
            "enum": ["transfer"],
            "description": "Transaction type."
          },
          "from_address": {
            "type": "string",
            "description": "Sender address."
          },
          "to_address": {
            "type": "string",
            "description": "Recipient address."
          },
          "amount": {
            "type": "string",
            "description": "Amount sent as a decimal string."
          },
          "token": {
            "type": "string",
            "description": "Token symbol (e.g., `USDC`, `USDT`, `ETH`)."
          },
          "chain": {
            "type": "string",
            "description": "CAIP-2 chain identifier."
          },
          "fee": {
            "type": "string",
            "description": "Network gas fee paid."
          },
          "status": {
            "type": "string",
            "enum": ["pending", "confirmed", "failed"],
            "description": "Transaction status."
          },
          "memo": {
            "type": "string",
            "description": "Optional memo string."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 creation timestamp."
          }
        }
      },
      "Policy": {
        "type": "object",
        "description": "A policy that controls what transactions an agent is allowed to execute.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique policy identifier (e.g., `pol_abc123`)."
          },
          "agent_id": {
            "type": "string",
            "description": "Agent this policy is attached to."
          },
          "type": {
            "type": "string",
            "enum": ["spending_limit", "address_control", "token_control", "velocity_control", "schedule", "human_approval"],
            "description": "Policy type."
          },
          "rules": {
            "$ref": "#/components/schemas/PolicyRules"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 creation timestamp."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 last-update timestamp."
          }
        }
      },
      "PolicyRules": {
        "type": "object",
        "description": "Policy rules object. Structure depends on the policy type.",
        "properties": {
          "max_transaction_amount": {
            "type": "string",
            "description": "Max per-transaction amount (spending_limit)."
          },
          "daily_limit": {
            "type": "string",
            "description": "Rolling 24-hour total (spending_limit)."
          },
          "monthly_limit": {
            "type": "string",
            "description": "Rolling 30-day total (spending_limit)."
          },
          "allowed_addresses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Whitelisted recipient addresses (address_control)."
          },
          "blocked_addresses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Blacklisted addresses (address_control)."
          },
          "allowed_tokens": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Permitted token symbols (token_control), e.g., `[\"USDC\", \"USDT\"]`."
          },
          "max_count": {
            "type": "integer",
            "description": "Maximum number of transactions in the window (velocity_control)."
          },
          "window_seconds": {
            "type": "integer",
            "description": "Time window in seconds (velocity_control)."
          },
          "timezone": {
            "type": "string",
            "description": "IANA timezone, e.g., `America/New_York` (schedule)."
          },
          "allowed_hours": {
            "type": "object",
            "description": "Object with `start` and `end` hour, 0-23 (schedule).",
            "properties": {
              "start": {
                "type": "integer",
                "minimum": 0,
                "maximum": 23,
                "description": "Start hour (0-23)."
              },
              "end": {
                "type": "integer",
                "minimum": 0,
                "maximum": 23,
                "description": "End hour (0-23)."
              }
            }
          },
          "allowed_days": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1,
              "maximum": 7
            },
            "description": "Allowed days (1=Monday, 7=Sunday) (schedule)."
          },
          "threshold": {
            "type": "string",
            "description": "Amount above which approval is required (human_approval)."
          },
          "timeout_seconds": {
            "type": "integer",
            "description": "Time before auto-reject (human_approval)."
          },
          "approvers": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            },
            "description": "Email addresses of approvers (human_approval)."
          }
        }
      },
      "Webhook": {
        "type": "object",
        "description": "A registered webhook endpoint for receiving real-time event notifications.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique webhook identifier (e.g., `whk_abc123`)."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "HTTPS URL that receives webhook events."
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of subscribed event types."
          },
          "status": {
            "type": "string",
            "enum": ["active", "inactive"],
            "description": "Webhook status."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 creation timestamp."
          }
        }
      },
      "X402Session": {
        "type": "object",
        "description": "An x402 payment session with a pre-authorized spending budget.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique session identifier (e.g., `sess_xyz789`)."
          },
          "agent_id": {
            "type": "string",
            "description": "Agent whose wallet funds the session."
          },
          "budget_limit": {
            "type": "string",
            "description": "Maximum total amount the session can spend."
          },
          "budget_spent": {
            "type": "string",
            "description": "Total amount spent so far."
          },
          "budget_remaining": {
            "type": "string",
            "description": "Remaining budget available."
          },
          "chain": {
            "type": "string",
            "description": "CAIP-2 chain identifier for settlement."
          },
          "status": {
            "type": "string",
            "enum": ["active", "expired", "deleted"],
            "description": "Session status."
          },
          "allowed_urls": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "description": "URLs this session is authorized to pay."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 expiration timestamp."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 creation timestamp."
          }
        }
      },
      "X402PayResult": {
        "type": "object",
        "description": "Result of an x402 payment negotiation.",
        "properties": {
          "ledger_id": {
            "type": "string",
            "description": "Internal ledger entry ID for this payment."
          },
          "amount": {
            "type": "string",
            "description": "Payment amount."
          },
          "fee_amount": {
            "type": "string",
            "description": "Platform fee deducted."
          },
          "fee_rate": {
            "type": "string",
            "description": "Fee percentage applied (based on tiered pricing)."
          },
          "token": {
            "type": "string",
            "description": "Token used for payment (e.g., `USDC`)."
          },
          "chain": {
            "type": "string",
            "description": "Chain used for settlement."
          },
          "status": {
            "type": "string",
            "enum": ["completed", "pending", "failed"],
            "description": "Payment status."
          },
          "payment_signature": {
            "type": "string",
            "description": "The `PAYMENT-SIGNATURE` value to include in the retry request to the target URL."
          }
        }
      },
      "PaginatedResponse": {
        "type": "object",
        "description": "Standard paginated response wrapper.",
        "properties": {
          "data": {
            "type": "array",
            "items": {},
            "description": "Array of resource objects."
          },
          "total": {
            "type": "integer",
            "description": "Total number of items matching the query."
          },
          "has_more": {
            "type": "boolean",
            "description": "Whether more pages are available."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Standard error response.",
        "required": ["code", "type", "message"],
        "properties": {
          "code": {
            "type": "string",
            "description": "Machine-readable error code."
          },
          "type": {
            "type": "string",
            "enum": [
              "invalid_request_error",
              "authentication_error",
              "authorization_error",
              "not_found_error",
              "rate_limit_error",
              "internal_error"
            ],
            "description": "Error type category."
          },
          "message": {
            "type": "string",
            "description": "Human-readable error description."
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request body or parameters.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "code": "invalid_request",
              "type": "invalid_request_error",
              "message": "The request body is missing required fields."
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid credentials.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "code": "authentication_failed",
              "type": "authentication_error",
              "message": "The provided API key is invalid or expired."
            }
          }
        }
      },
      "Forbidden": {
        "description": "Insufficient permissions.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "code": "insufficient_permissions",
              "type": "authorization_error",
              "message": "You do not have permission to perform this action."
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource does not exist.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "code": "resource_not_found",
              "type": "not_found_error",
              "message": "The requested resource was not found."
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "code": "rate_limit_exceeded",
              "type": "rate_limit_error",
              "message": "Too many requests. Please retry after a short delay."
            }
          }
        }
      },
      "InternalError": {
        "description": "Server-side error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "code": "server_error",
              "type": "internal_error",
              "message": "An unexpected error occurred. Please try again later."
            }
          }
        }
      }
    }
  }
}