@1claw/openapi-spec 0.15.2 → 0.16.0

package/README.md

@@ -42,13 +42,14 @@ import spec from "@1claw/openapi-spec/openapi.json";
 
 ## What's in the spec (v0.15.x)
 
+- **Billing — LLM token billing** — `GET /v1/billing/llm-token-billing`, `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)
 - **Vaults** — CRUD, CMEK enable/disable, key rotation with job tracking
 - **Secrets** — CRUD, versioning, CMEK-encrypted flag
 - **Agents** — CRUD with `auth_method` (api_key, mtls, oidc_client_credentials), auto-generated SSH keypairs, `token_ttl_seconds`, `vault_ids`, Intents API, transaction guardrails
 - **Policies** — Glob-based access control
 - **Sharing** — Links, user/agent shares, accept/decline
-- **Billing** — Subscriptions, credits, x402
+- **Billing** — Subscriptions, credits, x402, LLM token billing (see above)
 - **Audit** — Hash-chained event log
 - **Chains** — Supported blockchain registry
 - **Auth** — JWT, API keys, agent tokens, MFA, device flow, Google OAuth

package/openapi.json

@@ -1903,6 +1903,61 @@
         }
       }
     },
+    "/v1/agents/{agent_id}/transactions/sign": {
+      "post": {
+        "tags": [
+          "Transactions"
+        ],
+        "summary": "Sign a transaction without broadcasting",
+        "description": "Signs a transaction inside the server (or TEE when using Shroud) but does\n**not** broadcast it. The caller receives the raw `signed_tx` hex and\n`tx_hash` so it can submit to any RPC of its choosing.\n\nAll agent guardrails (allowlists, value caps, daily limits) are enforced\nexactly as for the submit endpoint. The signed transaction is recorded for\naudit and daily-limit tracking with `status: \"sign_only\"`.\n",
+        "operationId": "signTransaction",
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "quote"
+        },
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SignTransactionRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Transaction signed successfully (not broadcast)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SignTransactionResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "402": {
+            "$ref": "#/components/responses/PaymentRequired"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
     "/v1/agents/{agent_id}/transactions/simulate": {
       "post": {
         "tags": [
@@ -2763,6 +2818,72 @@
         }
       }
     },
+    "/v1/billing/llm-token-billing": {
+      "get": {
+        "tags": [
+          "Billing"
+        ],
+        "summary": "Get LLM token billing status",
+        "operationId": "getLlmTokenBilling",
+        "description": "Returns whether LLM token billing is enabled for the caller's org.",
+        "responses": {
+          "200": {
+            "description": "LLM token billing status",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/LlmTokenBillingStatus"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/billing/llm-token-billing/subscribe": {
+      "post": {
+        "tags": [
+          "Billing"
+        ],
+        "summary": "Subscribe to LLM token billing",
+        "operationId": "subscribeLlmTokenBilling",
+        "description": "Creates a Stripe Checkout session for the LLM token billing pricing plan. Returns a checkout URL to redirect the user. After the user completes checkout, a webhook activates LLM billing for the org.\n",
+        "responses": {
+          "200": {
+            "description": "Stripe Checkout URL",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/LlmCheckoutResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/billing/llm-token-billing/disable": {
+      "post": {
+        "tags": [
+          "Billing"
+        ],
+        "summary": "Disable LLM token billing",
+        "operationId": "disableLlmTokenBilling",
+        "description": "Disables LLM token billing for the org and cancels all active Stripe subscriptions for the LLM pricing plan. Agents will fall back to direct provider routing. You can re-enable it at any time.\n",
+        "responses": {
+          "200": {
+            "description": "LLM billing disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/LlmDisableResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/billing/overage-method": {
       "patch": {
         "tags": [
@@ -3827,10 +3948,11 @@
         "name": "include_signed_tx",
         "in": "query",
         "required": false,
-        "description": "Set to `true` or `1` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk. Only the literal values \"true\" or \"1\" enable inclusion; any other value or omission returns responses without signed_tx.\n",
+        "description": "Set to `true` or `1` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk. Only the literal values \"true\" or \"1\" enable inclusion; any other value or omission returns responses without signed_tx. Applies to GET /v1/agents/{agent_id}/transactions and GET /v1/agents/{agent_id}/transactions/{tx_id}.\n",
         "schema": {
           "type": "boolean",
-          "default": false
+          "default": false,
+          "example": false
         }
       }
     },
@@ -3969,13 +4091,13 @@
       "AgentTokenRequest": {
         "type": "object",
         "required": [
-          "agent_id",
           "api_key"
         ],
         "properties": {
           "agent_id": {
             "type": "string",
-            "format": "uuid"
+            "format": "uuid",
+            "description": "Optional when using key-only auth (ocv_ keys auto-resolve agent)"
           },
           "api_key": {
             "type": "string"
@@ -4126,11 +4248,17 @@
       "DeviceCodeRequest": {
         "type": "object",
         "required": [
-          "client_id"
+          "client_id",
+          "email"
         ],
         "properties": {
           "client_id": {
             "type": "string"
+          },
+          "email": {
+            "type": "string",
+            "format": "email",
+            "description": "Account email; only that user may approve the code in the dashboard."
           }
         }
       },
@@ -5539,6 +5667,112 @@
           "simulate_first": {
             "type": "boolean",
             "default": false
+          },
+          "mode": {
+            "type": "string",
+            "description": "Transaction mode",
+            "enum": [
+              "eoa",
+              "smart_account"
+            ],
+            "default": "eoa"
+          }
+        }
+      },
+      "SignTransactionRequest": {
+        "type": "object",
+        "required": [
+          "to",
+          "value",
+          "chain"
+        ],
+        "properties": {
+          "to": {
+            "type": "string",
+            "description": "Destination address (0x-prefixed)"
+          },
+          "value": {
+            "type": "string",
+            "description": "Value in ETH"
+          },
+          "chain": {
+            "type": "string",
+            "description": "Chain name or numeric ID"
+          },
+          "data": {
+            "type": "string",
+            "description": "Hex-encoded calldata"
+          },
+          "signing_key_path": {
+            "type": "string"
+          },
+          "nonce": {
+            "type": "integer"
+          },
+          "gas_price": {
+            "type": "string"
+          },
+          "gas_limit": {
+            "type": "integer"
+          },
+          "max_fee_per_gas": {
+            "type": "string"
+          },
+          "max_priority_fee_per_gas": {
+            "type": "string"
+          },
+          "simulate_first": {
+            "type": "boolean",
+            "default": false
+          }
+        }
+      },
+      "SignTransactionResponse": {
+        "type": "object",
+        "properties": {
+          "signed_tx": {
+            "type": "string",
+            "description": "Raw signed transaction hex (always included)"
+          },
+          "tx_hash": {
+            "type": "string"
+          },
+          "from": {
+            "type": "string",
+            "description": "Derived sender address"
+          },
+          "to": {
+            "type": "string"
+          },
+          "chain": {
+            "type": "string"
+          },
+          "chain_id": {
+            "type": "integer"
+          },
+          "nonce": {
+            "type": "integer"
+          },
+          "value_wei": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "sign_only"
+            ]
+          },
+          "simulation_id": {
+            "type": "string"
+          },
+          "simulation_status": {
+            "type": "string"
+          },
+          "max_fee_per_gas": {
+            "type": "string"
+          },
+          "max_priority_fee_per_gas": {
+            "type": "string"
           }
         }
       },
@@ -5612,6 +5846,7 @@
             "enum": [
               "pending",
               "signed",
+              "sign_only",
               "broadcast",
               "failed",
               "simulation_failed"
@@ -5620,7 +5855,7 @@
           "signed_tx": {
             "type": "string",
             "nullable": true,
-            "description": "Raw signed transaction hex. Omitted (null) by default to reduce exfiltration risk. Pass `include_signed_tx=true` query param on GET endpoints to include it. Always returned on the initial POST submission response.\n"
+            "description": "Raw signed transaction hex. On GET list and GET by id, this property is omitted by default (absent from the response). Pass `include_signed_tx=true` on those endpoints to include it. Always present on the initial POST submit response.\n"
           },
           "tx_hash": {
             "type": "string"
@@ -6310,6 +6545,38 @@
           }
         }
       },
+      "LlmTokenBillingStatus": {
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "type": "boolean"
+          },
+          "subscription_status": {
+            "type": "string",
+            "enum": [
+              "active",
+              "inactive"
+            ]
+          }
+        }
+      },
+      "LlmCheckoutResponse": {
+        "type": "object",
+        "properties": {
+          "checkout_url": {
+            "type": "string",
+            "format": "uri"
+          }
+        }
+      },
+      "LlmDisableResponse": {
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "type": "boolean"
+          }
+        }
+      },
       "CreditBalanceResponse": {
         "type": "object",
         "properties": {

package/openapi.yaml

@@ -1213,6 +1213,46 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/agents/{agent_id}/transactions/sign:
+        post:
+            tags: [Transactions]
+            summary: Sign a transaction without broadcasting
+            description: |
+                Signs a transaction inside the server (or TEE when using Shroud) but does
+                **not** broadcast it. The caller receives the raw `signed_tx` hex and
+                `tx_hash` so it can submit to any RPC of its choosing.
+
+                All agent guardrails (allowlists, value caps, daily limits) are enforced
+                exactly as for the submit endpoint. The signed transaction is recorded for
+                audit and daily-limit tracking with `status: "sign_only"`.
+            operationId: signTransaction
+            x-agentcash-auth:
+                mode: paid
+            x-payment-info:
+                protocols: [x402]
+                pricingMode: quote
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/SignTransactionRequest"
+            responses:
+                "200":
+                    description: Transaction signed successfully (not broadcast)
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SignTransactionResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "402":
+                    $ref: "#/components/responses/PaymentRequired"
+
     /v1/agents/{agent_id}/transactions/simulate:
         post:
             tags: [Transactions]
@@ -1760,6 +1800,58 @@ paths:
                             schema:
                                 $ref: "#/components/schemas/CreditTransactionsListResponse"
 
+    # ---------------------------------------------------------------------------
+    # LLM Token Billing
+    # ---------------------------------------------------------------------------
+
+    /v1/billing/llm-token-billing:
+        get:
+            tags: [Billing]
+            summary: Get LLM token billing status
+            operationId: getLlmTokenBilling
+            description: Returns whether LLM token billing is enabled for the caller's org.
+            responses:
+                "200":
+                    description: LLM token billing status
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/LlmTokenBillingStatus"
+
+    /v1/billing/llm-token-billing/subscribe:
+        post:
+            tags: [Billing]
+            summary: Subscribe to LLM token billing
+            operationId: subscribeLlmTokenBilling
+            description: >
+                Creates a Stripe Checkout session for the LLM token billing pricing plan.
+                Returns a checkout URL to redirect the user. After the user completes checkout,
+                a webhook activates LLM billing for the org.
+            responses:
+                "200":
+                    description: Stripe Checkout URL
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/LlmCheckoutResponse"
+
+    /v1/billing/llm-token-billing/disable:
+        post:
+            tags: [Billing]
+            summary: Disable LLM token billing
+            operationId: disableLlmTokenBilling
+            description: >
+                Disables LLM token billing for the org and cancels all active
+                Stripe subscriptions for the LLM pricing plan. Agents will fall
+                back to direct provider routing. You can re-enable it at any time.
+            responses:
+                "200":
+                    description: LLM billing disabled
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/LlmDisableResponse"
+
     /v1/billing/overage-method:
         patch:
             tags: [Billing]
@@ -2447,9 +2539,11 @@ components:
             description: >
                 Set to `true` or `1` to include the raw signed transaction hex in the response.
                 Omitted by default to reduce key exfiltration risk. Only the literal values "true" or "1" enable inclusion; any other value or omission returns responses without signed_tx.
+                Applies to GET /v1/agents/{agent_id}/transactions and GET /v1/agents/{agent_id}/transactions/{tx_id}.
             schema:
                 type: boolean
                 default: false
+                example: false
 
     responses:
         BadRequest:
@@ -2541,11 +2635,12 @@ components:
 
         AgentTokenRequest:
             type: object
-            required: [agent_id, api_key]
+            required: [api_key]
             properties:
                 agent_id:
                     type: string
                     format: uuid
+                    description: Optional when using key-only auth (ocv_ keys auto-resolve agent)
                 api_key:
                     type: string
 
@@ -2649,10 +2744,14 @@ components:
 
         DeviceCodeRequest:
             type: object
-            required: [client_id]
+            required: [client_id, email]
             properties:
                 client_id:
                     type: string
+                email:
+                    type: string
+                    format: email
+                    description: Account email; only that user may approve the code in the dashboard.
 
         DeviceCodeResponse:
             type: object
@@ -3634,6 +3733,76 @@ components:
                 simulate_first:
                     type: boolean
                     default: false
+                mode:
+                    type: string
+                    description: Transaction mode
+                    enum: [eoa, smart_account]
+                    default: eoa
+
+        SignTransactionRequest:
+            type: object
+            required: [to, value, chain]
+            properties:
+                to:
+                    type: string
+                    description: Destination address (0x-prefixed)
+                value:
+                    type: string
+                    description: Value in ETH
+                chain:
+                    type: string
+                    description: Chain name or numeric ID
+                data:
+                    type: string
+                    description: Hex-encoded calldata
+                signing_key_path:
+                    type: string
+                nonce:
+                    type: integer
+                gas_price:
+                    type: string
+                gas_limit:
+                    type: integer
+                max_fee_per_gas:
+                    type: string
+                max_priority_fee_per_gas:
+                    type: string
+                simulate_first:
+                    type: boolean
+                    default: false
+
+        SignTransactionResponse:
+            type: object
+            properties:
+                signed_tx:
+                    type: string
+                    description: Raw signed transaction hex (always included)
+                tx_hash:
+                    type: string
+                from:
+                    type: string
+                    description: Derived sender address
+                to:
+                    type: string
+                chain:
+                    type: string
+                chain_id:
+                    type: integer
+                nonce:
+                    type: integer
+                value_wei:
+                    type: string
+                status:
+                    type: string
+                    enum: [sign_only]
+                simulation_id:
+                    type: string
+                simulation_status:
+                    type: string
+                max_fee_per_gas:
+                    type: string
+                max_priority_fee_per_gas:
+                    type: string
 
         SimulateTransactionRequest:
             type: object
@@ -3681,14 +3850,12 @@ components:
                 status:
                     type: string
                     enum:
-                        [pending, signed, broadcast, failed, simulation_failed]
+                        [pending, signed, sign_only, broadcast, failed, simulation_failed]
                 signed_tx:
                     type: string
                     nullable: true
                     description: >
-                        Raw signed transaction hex. Omitted (null) by default to reduce exfiltration risk.
-                        Pass `include_signed_tx=true` query param on GET endpoints to include it.
-                        Always returned on the initial POST submission response.
+                        Raw signed transaction hex. On GET list and GET by id, this property is omitted by default (absent from the response). Pass `include_signed_tx=true` on those endpoints to include it. Always present on the initial POST submit response.
                 tx_hash:
                     type: string
                 error_message:
@@ -4162,6 +4329,28 @@ components:
                 limit:
                     type: integer
 
+        LlmTokenBillingStatus:
+            type: object
+            properties:
+                enabled:
+                    type: boolean
+                subscription_status:
+                    type: string
+                    enum: [active, inactive]
+
+        LlmCheckoutResponse:
+            type: object
+            properties:
+                checkout_url:
+                    type: string
+                    format: uri
+
+        LlmDisableResponse:
+            type: object
+            properties:
+                enabled:
+                    type: boolean
+
         CreditBalanceResponse:
             type: object
             properties:

package/package.json

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