@1claw/openapi-spec 0.21.0 → 0.22.0

package/README.md

@@ -40,13 +40,14 @@ openapi-generator generate \
 import spec from "@1claw/openapi-spec/openapi.json";
 ```
 
-## What's in the spec (v0.20.x — API `info.version` 2.10.x)
+## What's in the spec (v0.21.x — API `info.version` 2.11.x)
 
 - **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.
 - **Auth — password reset** — `POST /v1/auth/forgot-password`, `POST /v1/auth/reset-password` (public; anti-enumeration on forgot)
 - **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.
 - **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

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.11.0",
+    "version": "2.12.0",
     "description": "Secure secret management for AI agents. Provides vaults, secrets,\npolicy-based access control, agent identity, Intents API,\nsharing, billing, and audit logging.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
     "contact": {
       "email": "ops@1claw.xyz"
@@ -87,6 +87,10 @@
       "name": "Treasury",
       "description": "Multi-sig treasury wallets (Safe) and agent access requests"
     },
+    {
+      "name": "Treasury Wallets",
+      "description": "Multi-chain wallet generation for human users (replaces CDP embedded wallets)"
+    },
     {
       "name": "Admin",
       "description": "Platform administration"
@@ -4301,6 +4305,258 @@
         }
       }
     },
+    "/v1/treasury/wallets/generate": {
+      "post": {
+        "tags": [
+          "Treasury Wallets"
+        ],
+        "summary": "Generate multi-chain wallets for the authenticated user",
+        "description": "Generates keypairs for the requested chains (or all supported chains if omitted).\nPrivate keys are stored in a per-org `__treasury-keys` vault with tier-appropriate\nMPC custody. Skips chains where the user already has an active wallet. Requires\nPro or higher billing tier. Human users only — agents get 403.\n",
+        "operationId": "generateTreasuryWallets",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GenerateTreasuryWalletsRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Wallets generated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TreasuryWalletListResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/v1/treasury/wallets": {
+      "get": {
+        "tags": [
+          "Treasury Wallets"
+        ],
+        "summary": "List the authenticated user's treasury wallets",
+        "operationId": "listTreasuryWallets",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Wallet list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TreasuryWalletListResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/v1/treasury/wallets/{chain}": {
+      "get": {
+        "tags": [
+          "Treasury Wallets"
+        ],
+        "summary": "Get the user's active wallet for a specific chain",
+        "operationId": "getTreasuryWallet",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "chain",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Chain name (e.g. ethereum, solana, bitcoin)"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Wallet details",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TreasuryWalletResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Treasury Wallets"
+        ],
+        "summary": "Deactivate the user's wallet for a specific chain",
+        "operationId": "deactivateTreasuryWallet",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "chain",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Wallet deactivated"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/v1/treasury/wallets/{chain}/export": {
+      "post": {
+        "tags": [
+          "Treasury Wallets"
+        ],
+        "summary": "Export the private key for a treasury wallet",
+        "description": "Returns the raw private key hex for the user's active wallet on\nthe given chain. Audit-logged as `treasury_wallet.export`.\nHuman users only.\n",
+        "operationId": "exportTreasuryWallet",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "chain",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Private key exported",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TreasuryWalletExportResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/treasury/wallets/{chain}/rotate": {
+      "post": {
+        "tags": [
+          "Treasury Wallets"
+        ],
+        "summary": "Rotate the user's wallet key for a chain",
+        "description": "Generates a new keypair, deactivates the old wallet, and creates a\nnew active wallet. The old private key version is retained in the\nvault for audit. Requires Pro or higher.\n",
+        "operationId": "rotateTreasuryWallet",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "chain",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Wallet rotated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TreasuryWalletResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/admin/settings": {
       "get": {
         "tags": [
@@ -8978,6 +9234,73 @@
           }
         }
       },
+      "GenerateTreasuryWalletsRequest": {
+        "type": "object",
+        "properties": {
+          "chains": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Chains to generate wallets for (e.g. [\"ethereum\", \"solana\"]). Omit for all supported chains."
+          }
+        }
+      },
+      "TreasuryWalletResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "chain": {
+            "type": "string"
+          },
+          "curve": {
+            "type": "string",
+            "description": "Cryptographic curve (e.g. secp256k1, ed25519)"
+          },
+          "public_key_hex": {
+            "type": "string"
+          },
+          "address": {
+            "type": "string"
+          },
+          "is_active": {
+            "type": "boolean"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "TreasuryWalletListResponse": {
+        "type": "object",
+        "properties": {
+          "wallets": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/TreasuryWalletResponse"
+            }
+          }
+        }
+      },
+      "TreasuryWalletExportResponse": {
+        "type": "object",
+        "properties": {
+          "chain": {
+            "type": "string"
+          },
+          "address": {
+            "type": "string"
+          },
+          "private_key_hex": {
+            "type": "string",
+            "description": "Raw private key in hex encoding. Handle with extreme care."
+          }
+        }
+      },
       "PaymentRequirement": {
         "type": "object",
         "properties": {

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 2.11.0
+    version: 2.12.0
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -56,6 +56,8 @@ tags:
       description: IP rules and security configuration
     - name: Treasury
       description: Multi-sig treasury wallets (Safe) and agent access requests
+    - name: Treasury Wallets
+      description: Multi-chain wallet generation for human users (replaces CDP embedded wallets)
     - name: Admin
       description: Platform administration
     - name: Health
@@ -2819,6 +2821,172 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    # ---------------------------------------------------------------------------
+    # Treasury Wallets (multi-chain key generation for human users)
+    # ---------------------------------------------------------------------------
+
+    /v1/treasury/wallets/generate:
+        post:
+            tags: [Treasury Wallets]
+            summary: Generate multi-chain wallets for the authenticated user
+            description: |
+                Generates keypairs for the requested chains (or all supported chains if omitted).
+                Private keys are stored in a per-org `__treasury-keys` vault with tier-appropriate
+                MPC custody. Skips chains where the user already has an active wallet. Requires
+                Pro or higher billing tier. Human users only — agents get 403.
+            operationId: generateTreasuryWallets
+            security:
+                - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/GenerateTreasuryWalletsRequest"
+            responses:
+                "201":
+                    description: Wallets generated
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/TreasuryWalletListResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+
+    /v1/treasury/wallets:
+        get:
+            tags: [Treasury Wallets]
+            summary: List the authenticated user's treasury wallets
+            operationId: listTreasuryWallets
+            security:
+                - BearerAuth: []
+            responses:
+                "200":
+                    description: Wallet list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/TreasuryWalletListResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+
+    /v1/treasury/wallets/{chain}:
+        get:
+            tags: [Treasury Wallets]
+            summary: Get the user's active wallet for a specific chain
+            operationId: getTreasuryWallet
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: chain
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                  description: "Chain name (e.g. ethereum, solana, bitcoin)"
+            responses:
+                "200":
+                    description: Wallet details
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/TreasuryWalletResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+        delete:
+            tags: [Treasury Wallets]
+            summary: Deactivate the user's wallet for a specific chain
+            operationId: deactivateTreasuryWallet
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: chain
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+            responses:
+                "204":
+                    description: Wallet deactivated
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+
+    /v1/treasury/wallets/{chain}/export:
+        post:
+            tags: [Treasury Wallets]
+            summary: Export the private key for a treasury wallet
+            description: |
+                Returns the raw private key hex for the user's active wallet on
+                the given chain. Audit-logged as `treasury_wallet.export`.
+                Human users only.
+            operationId: exportTreasuryWallet
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: chain
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+            responses:
+                "200":
+                    description: Private key exported
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/TreasuryWalletExportResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/treasury/wallets/{chain}/rotate:
+        post:
+            tags: [Treasury Wallets]
+            summary: Rotate the user's wallet key for a chain
+            description: |
+                Generates a new keypair, deactivates the old wallet, and creates a
+                new active wallet. The old private key version is retained in the
+                vault for audit. Requires Pro or higher.
+            operationId: rotateTreasuryWallet
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: chain
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+            responses:
+                "200":
+                    description: Wallet rotated
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/TreasuryWalletResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # ---------------------------------------------------------------------------
     # Admin
     # ---------------------------------------------------------------------------
@@ -6048,6 +6216,57 @@ components:
                     type: string
                     format: date-time
 
+        # --- Treasury Wallets ---
+
+        GenerateTreasuryWalletsRequest:
+            type: object
+            properties:
+                chains:
+                    type: array
+                    items:
+                        type: string
+                    description: "Chains to generate wallets for (e.g. [\"ethereum\", \"solana\"]). Omit for all supported chains."
+
+        TreasuryWalletResponse:
+            type: object
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                chain:
+                    type: string
+                curve:
+                    type: string
+                    description: "Cryptographic curve (e.g. secp256k1, ed25519)"
+                public_key_hex:
+                    type: string
+                address:
+                    type: string
+                is_active:
+                    type: boolean
+                created_at:
+                    type: string
+                    format: date-time
+
+        TreasuryWalletListResponse:
+            type: object
+            properties:
+                wallets:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/TreasuryWalletResponse"
+
+        TreasuryWalletExportResponse:
+            type: object
+            properties:
+                chain:
+                    type: string
+                address:
+                    type: string
+                private_key_hex:
+                    type: string
+                    description: Raw private key in hex encoding. Handle with extreme care.
+
         # --- x402 ---
 
         PaymentRequirement:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@1claw/openapi-spec",
-    "version": "0.21.0",
+    "version": "0.22.0",
     "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API — generate clients in any language",
     "license": "MIT",
     "repository": {