@1claw/openapi-spec 0.7.0 → 0.9.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.2.0",
+    "version": "2.4.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"
@@ -22,6 +22,9 @@
       "description": "Shroud TEE Proxy (Intents API + LLM proxy)"
     }
   ],
+  "x-agentcash-guidance": {
+    "llmsTxtUrl": "https://1claw.xyz/llms.txt"
+  },
   "security": [
     {
       "BearerAuth": []
@@ -1152,6 +1155,16 @@
         ],
         "summary": "Store or update a secret",
         "operationId": "putSecret",
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "fixed",
+          "price": "0.0075"
+        },
         "parameters": [
           {
             "$ref": "#/components/parameters/VaultId"
@@ -1183,6 +1196,9 @@
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
+          },
+          "402": {
+            "$ref": "#/components/responses/PaymentRequired"
           }
         }
       },
@@ -1192,6 +1208,16 @@
         ],
         "summary": "Retrieve a decrypted secret",
         "operationId": "getSecret",
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "fixed",
+          "price": "0.0015"
+        },
         "parameters": [
           {
             "$ref": "#/components/parameters/VaultId"
@@ -1637,6 +1663,15 @@
           "Transactions"
         ],
         "summary": "Submit a transaction for signing",
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "quote"
+        },
         "description": "Replay protection: send an optional **Idempotency-Key** header (e.g. UUID or opaque string).\nDuplicate requests with the same key within 24 hours return the cached transaction response\n(no second sign/broadcast). Omit the header for non-idempotent submissions.\n",
         "operationId": "submitTransaction",
         "parameters": [
@@ -1684,6 +1719,9 @@
               }
             }
           },
+          "402": {
+            "$ref": "#/components/responses/PaymentRequired"
+          },
           "403": {
             "$ref": "#/components/responses/Forbidden"
           },
@@ -1785,6 +1823,16 @@
         ],
         "summary": "Simulate a transaction via Tenderly",
         "operationId": "simulateTransaction",
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "fixed",
+          "price": "0.075"
+        },
         "parameters": [
           {
             "$ref": "#/components/parameters/AgentId"
@@ -1814,6 +1862,9 @@
           "400": {
             "$ref": "#/components/responses/BadRequest"
           },
+          "402": {
+            "$ref": "#/components/responses/PaymentRequired"
+          },
           "403": {
             "$ref": "#/components/responses/Forbidden"
           }
@@ -1827,6 +1878,16 @@
         ],
         "summary": "Simulate a bundle of transactions",
         "operationId": "simulateBundle",
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "fixed",
+          "price": "0.075"
+        },
         "parameters": [
           {
             "$ref": "#/components/parameters/AgentId"
@@ -1855,6 +1916,9 @@
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
+          },
+          "402": {
+            "$ref": "#/components/responses/PaymentRequired"
           }
         }
       }
@@ -2039,6 +2103,16 @@
         ],
         "summary": "Create a share link for a secret",
         "operationId": "createShare",
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "fixed",
+          "price": "0.003"
+        },
         "parameters": [
           {
             "name": "secret_id",
@@ -2071,6 +2145,9 @@
               }
             }
           },
+          "402": {
+            "$ref": "#/components/responses/PaymentRequired"
+          },
           "404": {
             "$ref": "#/components/responses/NotFound"
           }
@@ -2085,6 +2162,16 @@
         "summary": "Access a shared secret",
         "operationId": "accessShare",
         "security": [],
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "fixed",
+          "price": "0.0015"
+        },
         "parameters": [
           {
             "name": "share_id",
@@ -2617,6 +2704,16 @@
         ],
         "summary": "Query audit events",
         "operationId": "queryAuditEvents",
+        "x-agentcash-auth": {
+          "mode": "paid"
+        },
+        "x-payment-info": {
+          "protocols": [
+            "x402"
+          ],
+          "pricingMode": "fixed",
+          "price": "0.0008"
+        },
         "parameters": [
           {
             "name": "resource_id",
@@ -2682,6 +2779,9 @@
                 }
               }
             }
+          },
+          "402": {
+            "$ref": "#/components/responses/PaymentRequired"
           }
         }
       }
@@ -3020,7 +3120,7 @@
         ],
         "summary": "Set org billing tier (without Stripe)",
         "operationId": "adminSetBillingTier",
-        "description": "Manually set an organization's billing tier to free, pro, or business.\nFor testing and manual upgrades — does not create a Stripe subscription.\nSetting to \"pro\" or \"business\" sets period_end to +1 year.\nSetting to \"free\" clears subscription data.\n",
+        "description": "Manually set an organization's billing tier to free, pro, business, or enterprise.\nFor testing, manual upgrades, and trial grants — does not create a Stripe subscription.\nSetting to \"pro\", \"business\", or \"enterprise\" sets period_end to now + duration_days (default 365).\nSetting to \"free\" clears subscription data. Use duration_days: 90 for a 3-month trial.\n",
         "parameters": [
           {
             "name": "org_id",
@@ -5576,8 +5676,15 @@
             "enum": [
               "free",
               "pro",
-              "business"
+              "business",
+              "enterprise"
             ]
+          },
+          "duration_days": {
+            "type": "integer",
+            "description": "How many days the tier lasts (default 365). Use 90 for a 3-month trial.",
+            "minimum": 1,
+            "maximum": 3650
           }
         }
       },

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
   title: 1Claw API
-  version: 2.2.0
+  version: 2.4.0
   description: |
     Secure secret management for AI agents. Provides vaults, secrets,
     policy-based access control, agent identity, Intents API,
@@ -21,6 +21,9 @@ servers:
   - url: https://shroud.1claw.xyz
     description: Shroud TEE Proxy (Intents API + LLM proxy)
 
+x-agentcash-guidance:
+  llmsTxtUrl: https://1claw.xyz/llms.txt
+
 security:
   - BearerAuth: []
 
@@ -745,6 +748,12 @@ paths:
       tags: [Secrets]
       summary: Store or update a secret
       operationId: putSecret
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: fixed
+        price: "0.0075"
       parameters:
         - $ref: "#/components/parameters/VaultId"
         - $ref: "#/components/parameters/SecretPath"
@@ -763,10 +772,18 @@ paths:
                 $ref: "#/components/schemas/SecretMetadataResponse"
         "400":
           $ref: "#/components/responses/BadRequest"
+        "402":
+          $ref: "#/components/responses/PaymentRequired"
     get:
       tags: [Secrets]
       summary: Retrieve a decrypted secret
       operationId: getSecret
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: fixed
+        price: "0.0015"
       parameters:
         - $ref: "#/components/parameters/VaultId"
         - $ref: "#/components/parameters/SecretPath"
@@ -1047,6 +1064,11 @@ paths:
     post:
       tags: [Transactions]
       summary: Submit a transaction for signing
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: quote
       description: |
         Replay protection: send an optional **Idempotency-Key** header (e.g. UUID or opaque string).
         Duplicate requests with the same key within 24 hours return the cached transaction response
@@ -1079,6 +1101,8 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/TransactionResponse"
+        "402":
+          $ref: "#/components/responses/PaymentRequired"
         "403":
           $ref: "#/components/responses/Forbidden"
         "409":
@@ -1137,6 +1161,12 @@ paths:
       tags: [Transactions]
       summary: Simulate a transaction via Tenderly
       operationId: simulateTransaction
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: fixed
+        price: "0.075"
       parameters:
         - $ref: "#/components/parameters/AgentId"
       requestBody:
@@ -1156,12 +1186,20 @@ paths:
           $ref: "#/components/responses/BadRequest"
         "403":
           $ref: "#/components/responses/Forbidden"
+        "402":
+          $ref: "#/components/responses/PaymentRequired"
 
   /v1/agents/{agent_id}/transactions/simulate-bundle:
     post:
       tags: [Transactions]
       summary: Simulate a bundle of transactions
       operationId: simulateBundle
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: fixed
+        price: "0.075"
       parameters:
         - $ref: "#/components/parameters/AgentId"
       requestBody:
@@ -1179,6 +1217,8 @@ paths:
                 $ref: "#/components/schemas/BundleSimulationResponse"
         "400":
           $ref: "#/components/responses/BadRequest"
+        "402":
+          $ref: "#/components/responses/PaymentRequired"
 
   # ---------------------------------------------------------------------------
   # Chains
@@ -1300,6 +1340,12 @@ paths:
       tags: [Sharing]
       summary: Create a share link for a secret
       operationId: createShare
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: fixed
+        price: "0.003"
       parameters:
         - name: secret_id
           in: path
@@ -1320,6 +1366,8 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ShareResponse"
+        "402":
+          $ref: "#/components/responses/PaymentRequired"
         "404":
           $ref: "#/components/responses/NotFound"
 
@@ -1329,6 +1377,12 @@ paths:
       summary: Access a shared secret
       operationId: accessShare
       security: []
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: fixed
+        price: "0.0015"
       parameters:
         - name: share_id
           in: path
@@ -1671,6 +1725,12 @@ paths:
       tags: [Audit]
       summary: Query audit events
       operationId: queryAuditEvents
+      x-agentcash-auth:
+        mode: paid
+      x-payment-info:
+        protocols: [x402]
+        pricingMode: fixed
+        price: "0.0008"
       parameters:
         - name: resource_id
           in: query
@@ -1711,6 +1771,8 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/AuditEventsResponse"
+        "402":
+          $ref: "#/components/responses/PaymentRequired"
 
   # ---------------------------------------------------------------------------
   # Security (IP Rules)
@@ -1926,10 +1988,10 @@ paths:
       summary: Set org billing tier (without Stripe)
       operationId: adminSetBillingTier
       description: |
-        Manually set an organization's billing tier to free, pro, or business.
-        For testing and manual upgrades — does not create a Stripe subscription.
-        Setting to "pro" or "business" sets period_end to +1 year.
-        Setting to "free" clears subscription data.
+        Manually set an organization's billing tier to free, pro, business, or enterprise.
+        For testing, manual upgrades, and trial grants — does not create a Stripe subscription.
+        Setting to "pro", "business", or "enterprise" sets period_end to now + duration_days (default 365).
+        Setting to "free" clears subscription data. Use duration_days: 90 for a 3-month trial.
       parameters:
         - name: org_id
           in: path
@@ -3695,7 +3757,12 @@ components:
       properties:
         tier:
           type: string
-          enum: [free, pro, business]
+          enum: [free, pro, business, enterprise]
+        duration_days:
+          type: integer
+          description: How many days the tier lasts (default 365). Use 90 for a 3-month trial.
+          minimum: 1
+          maximum: 3650
 
     # --- x402 ---
 

package/package.json

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