@1claw/openapi-spec 0.28.0 → 0.29.0

package/README.md

@@ -40,7 +40,7 @@ openapi-generator generate \
 import spec from "@1claw/openapi-spec/openapi.json";
 ```
 
-## What's in the spec (v0.25.0 — API `info.version` 2.14.0)
+## What's in the spec (v0.28.0 — API `info.version` 2.15.0)
 
 - **OIDC Federation (1claw as IdP)** — `GET /.well-known/openid-configuration` (public discovery: issuer, jwks_uri, supported algs `["EdDSA","RS256"]`, supported grant types incl. token-exchange), `GET /.well-known/jwks.json` (public JWKS — every active EdDSA + RS256 key version, keyed by deterministic `kid`), `POST /v1/auth/federated-token` (RFC 8693 token exchange — accepts JSON or `application/x-www-form-urlencoded`; subject token is an agent JWT or `ocv_` API key; returns RS256 JWT scoped to `audience`). Agent fields: `federation_enabled`, `federation_audiences[]`, `federated_token_ttl_seconds`. Designed for Anthropic Workload Identity Federation, GCP STS, AWS STS, etc.
 - **Auth — agent JWT** — `POST /v1/auth/agent-token` documents optional JWT claim **`shroud_config`** when the agent has Shroud enabled (mirrors DB; consumed by Shroud PolicyEngine on LLM requests). Re-exchange after changing agent Shroud settings. Federation tokens use a separate KMS RSA-2048 key and are signed RS256.
@@ -52,6 +52,8 @@ import spec from "@1claw/openapi-spec/openapi.json";
 - **Billing — LLM token billing** — `GET /v1/billing/llm-token-billing` (`LlmTokenBillingStatus`: `enabled`, `subscription_status`, optional `credit_balance`, optional `billing_cycle_usage` with `metered_lines[]`), `POST .../subscribe`, `POST .../disable` (Stripe AI Gateway add-on; optional org feature)
 - **Treasury** — Safe multisig treasuries: `POST/GET /v1/treasury`, `GET/PATCH/DELETE /v1/treasury/{id}`, signers, agent access requests (`requests[]` on list)
 - **Treasury Wallets** — Multi-chain wallet generation for human users (replaces CDP embedded wallets): `POST /v1/treasury/wallets/generate`, `GET /v1/treasury/wallets`, `GET /v1/treasury/wallets/{chain}`, `POST .../export`, `POST .../rotate`, `DELETE /v1/treasury/wallets/{chain}`. Supported chains: ethereum, bitcoin, solana, xrp, cardano, tron. Private keys stored in per-org `__treasury-keys` vault with tier-appropriate MPC custody.
+- **Treasury Proposals** — Full propose/confirm/execute pipeline for Safe multisig transactions: `POST /v1/treasury/{id}/proposals`, `GET .../proposals`, `GET .../proposals/{pid}`, `POST .../proposals/{pid}/sign`, `POST .../proposals/{pid}/execute`, `DELETE .../proposals/{pid}`. Auto-execute when threshold met.
+- **Smart Accounts** — Per-agent multi-chain Safe accounts: `POST /v1/agents/{id}/smart-accounts`, `GET /v1/agents/{id}` returns `smart_accounts[]`. One EOA signer per agent, Intents API resolves Safe by `chain_id`.
 - **Vaults** — CRUD, CMEK enable/disable, key rotation with job tracking, MPC enable/disable (`POST /v1/vaults/{id}/mpc`, `DELETE /v1/vaults/{id}/mpc`)
 - **Secrets** — CRUD, versioning, CMEK-encrypted flag, `client_share` in responses (MPC vaults)
 - **Agents** — CRUD with `auth_method` (api_key, mtls, oidc_client_credentials), auto-generated SSH keypairs, `token_ttl_seconds`, `vault_ids`, Intents API, transaction guardrails (`tx_to_allowlist`, `tx_max_value_eth`, `tx_daily_limit_eth`, `tx_allowed_chains`), **OIDC federation knobs** (`federation_enabled`, `federation_audiences`, `federated_token_ttl_seconds`); **`GET /v1/agents/{id}`** includes **`tx_spent_today_eth`** (rolling UTC-day spend from recorded txs) for clients such as **Shroud** that enforce the daily cap alongside per-tx limits

package/openapi.json

@@ -103,6 +103,14 @@
       "name": "Approvals",
       "description": "Human-in-the-loop approval workflow for agent actions"
     },
+    {
+      "name": "Signing Keys",
+      "description": "Per-agent multi-chain signing key management"
+    },
+    {
+      "name": "Webhooks",
+      "description": "Event webhook registration and management"
+    },
     {
       "name": "Platform",
       "description": "Platform API for developers building on 1Claw (plt_ keys, user provisioning, bootstrap templates)"
@@ -3630,6 +3638,55 @@
         }
       }
     },
+    "/v1/agents/{agent_id}/signing-keys/{chain}/balance": {
+      "get": {
+        "tags": [
+          "Signing Keys"
+        ],
+        "summary": "Get signing key balance",
+        "description": "Returns the native token balance for the agent's signing key address\non the specified chain.\n",
+        "operationId": "getSigningKeyBalance",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "chain",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Signing key balance",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SigningKeyBalanceResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/agents/{agent_id}/sign": {
       "post": {
         "tags": [
@@ -5741,9 +5798,405 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
-          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/treasury/wallets/{chain}/balance": {
+      "get": {
+        "tags": [
+          "Treasury Wallets"
+        ],
+        "summary": "Get wallet balance",
+        "description": "Returns the native and token balances for the user's active wallet\non the specified chain.\n",
+        "operationId": "getTreasuryWalletBalance",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "chain",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "tokens",
+            "in": "query",
+            "required": false,
+            "description": "Optional list of ERC-20 contract addresses to query balances for",
+            "schema": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Wallet balance",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TreasuryWalletBalanceResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/treasury/wallets/{chain}/send": {
+      "post": {
+        "tags": [
+          "Treasury Wallets"
+        ],
+        "summary": "Send from treasury wallet",
+        "description": "Signs and broadcasts a transaction from the user's active wallet on\nthe specified chain. Requires re-authentication via `X-Auth-Confirm`\nheader (account password). Human users only.\n",
+        "operationId": "sendFromTreasuryWallet",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "chain",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "X-Auth-Confirm",
+            "in": "header",
+            "required": true,
+            "description": "Account password for re-authentication",
+            "schema": {
+              "type": "string",
+              "format": "password"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TreasuryWalletSendRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Transaction sent",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TreasuryWalletSendResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/treasury/wallets/{chain}/swap": {
+      "post": {
+        "tags": [
+          "Treasury Wallets"
+        ],
+        "summary": "Swap tokens via DEX aggregator",
+        "description": "Executes a token swap through a DEX aggregator from the user's active\nwallet on the specified chain. Requires re-authentication via\n`X-Auth-Confirm` header (account password). Human users only.\n",
+        "operationId": "swapFromTreasuryWallet",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "chain",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "X-Auth-Confirm",
+            "in": "header",
+            "required": true,
+            "description": "Account password for re-authentication",
+            "schema": {
+              "type": "string",
+              "format": "password"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TreasuryWalletSwapRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Swap executed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TreasuryWalletSwapResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/webhooks": {
+      "post": {
+        "tags": [
+          "Webhooks"
+        ],
+        "summary": "Register a webhook",
+        "operationId": "createWebhook",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateWebhookRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Webhook registered",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WebhookCreatedResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "Webhooks"
+        ],
+        "summary": "List webhooks",
+        "operationId": "listWebhooks",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Webhook list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WebhookListResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      }
+    },
+    "/v1/webhooks/{id}": {
+      "get": {
+        "tags": [
+          "Webhooks"
+        ],
+        "summary": "Get webhook",
+        "operationId": "getWebhook",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Webhook details",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WebhookResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "patch": {
+        "tags": [
+          "Webhooks"
+        ],
+        "summary": "Update webhook",
+        "operationId": "updateWebhook",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateWebhookRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Webhook updated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WebhookResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Webhooks"
+        ],
+        "summary": "Delete webhook",
+        "operationId": "deleteWebhook",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Webhook deleted"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
           "404": {
             "$ref": "#/components/responses/NotFound"
           }
@@ -9640,6 +10093,11 @@
               "smart_account"
             ],
             "default": "eoa"
+          },
+          "gasless": {
+            "type": "boolean",
+            "description": "Whether to submit as a gasless (sponsored) transaction",
+            "default": false
           }
         }
       },
@@ -11633,6 +12091,324 @@
           }
         }
       },
+      "TreasuryWalletBalanceResponse": {
+        "type": "object",
+        "required": [
+          "chain",
+          "address",
+          "native"
+        ],
+        "properties": {
+          "chain": {
+            "type": "string"
+          },
+          "address": {
+            "type": "string"
+          },
+          "native": {
+            "type": "object",
+            "required": [
+              "symbol",
+              "balance_wei",
+              "balance_display"
+            ],
+            "properties": {
+              "symbol": {
+                "type": "string"
+              },
+              "balance_wei": {
+                "type": "string"
+              },
+              "balance_display": {
+                "type": "string"
+              }
+            }
+          },
+          "tokens": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "contract_address",
+                "balance_raw"
+              ],
+              "properties": {
+                "contract_address": {
+                  "type": "string"
+                },
+                "balance_raw": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      },
+      "TreasuryWalletSendRequest": {
+        "type": "object",
+        "required": [
+          "to",
+          "value_wei"
+        ],
+        "properties": {
+          "to": {
+            "type": "string",
+            "description": "Destination address (0x-prefixed)"
+          },
+          "value_wei": {
+            "type": "string",
+            "description": "Value in wei"
+          },
+          "data": {
+            "type": "string",
+            "description": "Hex-encoded calldata (optional)"
+          },
+          "gas_limit": {
+            "type": "integer",
+            "description": "Gas limit override"
+          }
+        }
+      },
+      "TreasuryWalletSendResponse": {
+        "type": "object",
+        "required": [
+          "tx_hash",
+          "from",
+          "to",
+          "value_wei",
+          "chain",
+          "status"
+        ],
+        "properties": {
+          "tx_hash": {
+            "type": "string"
+          },
+          "from": {
+            "type": "string"
+          },
+          "to": {
+            "type": "string"
+          },
+          "value_wei": {
+            "type": "string"
+          },
+          "chain": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string"
+          }
+        }
+      },
+      "TreasuryWalletSwapRequest": {
+        "type": "object",
+        "required": [
+          "sell_token",
+          "buy_token",
+          "sell_amount"
+        ],
+        "properties": {
+          "sell_token": {
+            "type": "string",
+            "description": "Address of the token to sell (or \"native\" for ETH)"
+          },
+          "buy_token": {
+            "type": "string",
+            "description": "Address of the token to buy (or \"native\" for ETH)"
+          },
+          "sell_amount": {
+            "type": "string",
+            "description": "Amount to sell in token's smallest unit"
+          }
+        }
+      },
+      "TreasuryWalletSwapResponse": {
+        "type": "object",
+        "required": [
+          "tx_hash",
+          "sell_token",
+          "buy_token",
+          "sell_amount",
+          "buy_amount",
+          "chain",
+          "status"
+        ],
+        "properties": {
+          "tx_hash": {
+            "type": "string"
+          },
+          "sell_token": {
+            "type": "string"
+          },
+          "buy_token": {
+            "type": "string"
+          },
+          "sell_amount": {
+            "type": "string"
+          },
+          "buy_amount": {
+            "type": "string"
+          },
+          "chain": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string"
+          }
+        }
+      },
+      "CreateWebhookRequest": {
+        "type": "object",
+        "required": [
+          "url",
+          "events"
+        ],
+        "properties": {
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "HTTPS URL to deliver webhook events to"
+          },
+          "events": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Event types to subscribe to"
+          },
+          "description": {
+            "type": "string"
+          }
+        }
+      },
+      "UpdateWebhookRequest": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "format": "uri"
+          },
+          "events": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "is_active": {
+            "type": "boolean"
+          },
+          "description": {
+            "type": "string"
+          }
+        }
+      },
+      "WebhookCreatedResponse": {
+        "type": "object",
+        "required": [
+          "id",
+          "url",
+          "events",
+          "secret",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "url": {
+            "type": "string",
+            "format": "uri"
+          },
+          "events": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "secret": {
+            "type": "string",
+            "description": "HMAC signing secret for verifying payloads (shown only once)"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "WebhookResponse": {
+        "type": "object",
+        "required": [
+          "id",
+          "url",
+          "events",
+          "is_active",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "url": {
+            "type": "string",
+            "format": "uri"
+          },
+          "events": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "is_active": {
+            "type": "boolean"
+          },
+          "description": {
+            "type": "string"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "WebhookListResponse": {
+        "type": "object",
+        "required": [
+          "webhooks"
+        ],
+        "properties": {
+          "webhooks": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/WebhookResponse"
+            }
+          }
+        }
+      },
+      "SigningKeyBalanceResponse": {
+        "type": "object",
+        "required": [
+          "chain",
+          "address",
+          "balance_wei",
+          "balance_display"
+        ],
+        "properties": {
+          "chain": {
+            "type": "string"
+          },
+          "address": {
+            "type": "string"
+          },
+          "balance_wei": {
+            "type": "string"
+          },
+          "balance_display": {
+            "type": "string"
+          }
+        }
+      },
       "PaymentRequirement": {
         "type": "object",
         "properties": {

package/openapi.yaml

@@ -64,6 +64,10 @@ tags:
       description: Service health checks
     - name: Approvals
       description: Human-in-the-loop approval workflow for agent actions
+    - name: Signing Keys
+      description: Per-agent multi-chain signing key management
+    - name: Webhooks
+      description: Event webhook registration and management
     - name: Platform
       description: Platform API for developers building on 1Claw (plt_ keys, user provisioning, bootstrap templates)
 
@@ -2378,6 +2382,37 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/agents/{agent_id}/signing-keys/{chain}/balance:
+        get:
+            tags: [Signing Keys]
+            summary: Get signing key balance
+            description: |
+                Returns the native token balance for the agent's signing key address
+                on the specified chain.
+            operationId: getSigningKeyBalance
+            security:
+                - BearerAuth: []
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: chain
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+            responses:
+                "200":
+                    description: Signing key balance
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SigningKeyBalanceResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # ---------------------------------------------------------------------------
     # Unified Signing Intent
     # ---------------------------------------------------------------------------
@@ -3744,6 +3779,258 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/treasury/wallets/{chain}/balance:
+        get:
+            tags: [Treasury Wallets]
+            summary: Get wallet balance
+            description: |
+                Returns the native and token balances for the user's active wallet
+                on the specified chain.
+            operationId: getTreasuryWalletBalance
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: chain
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                - name: tokens
+                  in: query
+                  required: false
+                  description: Optional list of ERC-20 contract addresses to query balances for
+                  schema:
+                      type: array
+                      items:
+                          type: string
+            responses:
+                "200":
+                    description: Wallet balance
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/TreasuryWalletBalanceResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/treasury/wallets/{chain}/send:
+        post:
+            tags: [Treasury Wallets]
+            summary: Send from treasury wallet
+            description: |
+                Signs and broadcasts a transaction from the user's active wallet on
+                the specified chain. Requires re-authentication via `X-Auth-Confirm`
+                header (account password). Human users only.
+            operationId: sendFromTreasuryWallet
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: chain
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                - name: X-Auth-Confirm
+                  in: header
+                  required: true
+                  description: Account password for re-authentication
+                  schema:
+                      type: string
+                      format: password
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/TreasuryWalletSendRequest"
+            responses:
+                "200":
+                    description: Transaction sent
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/TreasuryWalletSendResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/treasury/wallets/{chain}/swap:
+        post:
+            tags: [Treasury Wallets]
+            summary: Swap tokens via DEX aggregator
+            description: |
+                Executes a token swap through a DEX aggregator from the user's active
+                wallet on the specified chain. Requires re-authentication via
+                `X-Auth-Confirm` header (account password). Human users only.
+            operationId: swapFromTreasuryWallet
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: chain
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                - name: X-Auth-Confirm
+                  in: header
+                  required: true
+                  description: Account password for re-authentication
+                  schema:
+                      type: string
+                      format: password
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/TreasuryWalletSwapRequest"
+            responses:
+                "200":
+                    description: Swap executed
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/TreasuryWalletSwapResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    # ---------------------------------------------------------------------------
+    # Webhooks
+    # ---------------------------------------------------------------------------
+
+    /v1/webhooks:
+        post:
+            tags: [Webhooks]
+            summary: Register a webhook
+            operationId: createWebhook
+            security:
+                - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateWebhookRequest"
+            responses:
+                "201":
+                    description: Webhook registered
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/WebhookCreatedResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+        get:
+            tags: [Webhooks]
+            summary: List webhooks
+            operationId: listWebhooks
+            security:
+                - BearerAuth: []
+            responses:
+                "200":
+                    description: Webhook list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/WebhookListResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+
+    /v1/webhooks/{id}:
+        get:
+            tags: [Webhooks]
+            summary: Get webhook
+            operationId: getWebhook
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Webhook details
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/WebhookResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+        patch:
+            tags: [Webhooks]
+            summary: Update webhook
+            operationId: updateWebhook
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/UpdateWebhookRequest"
+            responses:
+                "200":
+                    description: Webhook updated
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/WebhookResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+        delete:
+            tags: [Webhooks]
+            summary: Delete webhook
+            operationId: deleteWebhook
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "204":
+                    description: Webhook deleted
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # ---------------------------------------------------------------------------
     # Admin
     # ---------------------------------------------------------------------------
@@ -6374,6 +6661,10 @@ components:
                     description: Transaction mode
                     enum: [eoa, smart_account]
                     default: eoa
+                gasless:
+                    type: boolean
+                    description: Whether to submit as a gasless (sponsored) transaction
+                    default: false
 
         SignTransactionRequest:
             type: object
@@ -7742,6 +8033,202 @@ components:
                     type: string
                     description: Raw private key in hex encoding. Handle with extreme care.
 
+        TreasuryWalletBalanceResponse:
+            type: object
+            required: [chain, address, native]
+            properties:
+                chain:
+                    type: string
+                address:
+                    type: string
+                native:
+                    type: object
+                    required: [symbol, balance_wei, balance_display]
+                    properties:
+                        symbol:
+                            type: string
+                        balance_wei:
+                            type: string
+                        balance_display:
+                            type: string
+                tokens:
+                    type: array
+                    items:
+                        type: object
+                        required: [contract_address, balance_raw]
+                        properties:
+                            contract_address:
+                                type: string
+                            balance_raw:
+                                type: string
+
+        TreasuryWalletSendRequest:
+            type: object
+            required: [to, value_wei]
+            properties:
+                to:
+                    type: string
+                    description: Destination address (0x-prefixed)
+                value_wei:
+                    type: string
+                    description: Value in wei
+                data:
+                    type: string
+                    description: Hex-encoded calldata (optional)
+                gas_limit:
+                    type: integer
+                    description: Gas limit override
+
+        TreasuryWalletSendResponse:
+            type: object
+            required: [tx_hash, from, to, value_wei, chain, status]
+            properties:
+                tx_hash:
+                    type: string
+                from:
+                    type: string
+                to:
+                    type: string
+                value_wei:
+                    type: string
+                chain:
+                    type: string
+                status:
+                    type: string
+
+        TreasuryWalletSwapRequest:
+            type: object
+            required: [sell_token, buy_token, sell_amount]
+            properties:
+                sell_token:
+                    type: string
+                    description: Address of the token to sell (or "native" for ETH)
+                buy_token:
+                    type: string
+                    description: Address of the token to buy (or "native" for ETH)
+                sell_amount:
+                    type: string
+                    description: Amount to sell in token's smallest unit
+
+        TreasuryWalletSwapResponse:
+            type: object
+            required: [tx_hash, sell_token, buy_token, sell_amount, buy_amount, chain, status]
+            properties:
+                tx_hash:
+                    type: string
+                sell_token:
+                    type: string
+                buy_token:
+                    type: string
+                sell_amount:
+                    type: string
+                buy_amount:
+                    type: string
+                chain:
+                    type: string
+                status:
+                    type: string
+
+        # --- Webhooks ---
+
+        CreateWebhookRequest:
+            type: object
+            required: [url, events]
+            properties:
+                url:
+                    type: string
+                    format: uri
+                    description: HTTPS URL to deliver webhook events to
+                events:
+                    type: array
+                    items:
+                        type: string
+                    description: Event types to subscribe to
+                description:
+                    type: string
+
+        UpdateWebhookRequest:
+            type: object
+            properties:
+                url:
+                    type: string
+                    format: uri
+                events:
+                    type: array
+                    items:
+                        type: string
+                is_active:
+                    type: boolean
+                description:
+                    type: string
+
+        WebhookCreatedResponse:
+            type: object
+            required: [id, url, events, secret, created_at]
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                url:
+                    type: string
+                    format: uri
+                events:
+                    type: array
+                    items:
+                        type: string
+                secret:
+                    type: string
+                    description: HMAC signing secret for verifying payloads (shown only once)
+                created_at:
+                    type: string
+                    format: date-time
+
+        WebhookResponse:
+            type: object
+            required: [id, url, events, is_active, created_at]
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                url:
+                    type: string
+                    format: uri
+                events:
+                    type: array
+                    items:
+                        type: string
+                is_active:
+                    type: boolean
+                description:
+                    type: string
+                created_at:
+                    type: string
+                    format: date-time
+
+        WebhookListResponse:
+            type: object
+            required: [webhooks]
+            properties:
+                webhooks:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/WebhookResponse"
+
+        # --- Signing Key Balance ---
+
+        SigningKeyBalanceResponse:
+            type: object
+            required: [chain, address, balance_wei, balance_display]
+            properties:
+                chain:
+                    type: string
+                address:
+                    type: string
+                balance_wei:
+                    type: string
+                balance_display:
+                    type: string
+
         # --- x402 ---
 
         PaymentRequirement:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@1claw/openapi-spec",
-  "version": "0.28.0",
-  "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API \u2014 generate clients in any language",
+  "version": "0.29.0",
+  "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API — generate clients in any language",
   "license": "MIT",
   "repository": {
     "type": "git",