@1claw/openapi-spec 0.41.1 → 0.41.3

package/openapi.json

@@ -130,6 +130,10 @@
     {
       "name": "Execution Intents",
       "description": "Execute HTTP calls, queries, and more through pre-configured bindings"
+    },
+    {
+      "name": "Payment Cards",
+      "description": "Order prepaid/gift cards via x402, then reveal, refresh, and void them"
     }
   ],
   "paths": {
@@ -9957,6 +9961,328 @@
           }
         }
       }
+    },
+    "/v1/agents/{agent_id}/cards/order": {
+      "post": {
+        "tags": [
+          "Payment Cards"
+        ],
+        "summary": "Order a payment card (x402)",
+        "description": "Order a prepaid or gift card for an agent. Drives the x402 payment flow server-side using the agent's Ethereum signing key (funded with USDC on Base). Requires `cards_enabled` on the agent and a Pro or higher plan. An `Idempotency-Key` header is required.\n",
+        "operationId": "orderCard",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "Idempotency-Key",
+            "in": "header",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/OrderCardRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Card order accepted (status pending)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CardResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          }
+        }
+      }
+    },
+    "/v1/cards": {
+      "get": {
+        "tags": [
+          "Payment Cards"
+        ],
+        "summary": "List payment cards",
+        "description": "List cards for the caller (agents see only their own). Always masked (last4 only).",
+        "operationId": "listCards",
+        "responses": {
+          "200": {
+            "description": "Card list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CardListResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/cards/import": {
+      "post": {
+        "tags": [
+          "Payment Cards"
+        ],
+        "summary": "Import a card (human-only)",
+        "description": "Manually import an existing card. Full storage mode — PAN stored encrypted, CVV as a one-time-read secret. Human-only.",
+        "operationId": "importCard",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ImportCardRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Card imported",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CardResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/v1/cards/gift-cards/search": {
+      "post": {
+        "tags": [
+          "Payment Cards"
+        ],
+        "summary": "Search gift-card brands",
+        "description": "Search available Laso gift-card brands/servers for the org's Laso account.",
+        "operationId": "searchGiftCards",
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SearchGiftCardsRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Available gift-card brands (provider-shaped payload)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/cards/{card_id}": {
+      "get": {
+        "tags": [
+          "Payment Cards"
+        ],
+        "summary": "Get a payment card",
+        "description": "Get a single card (masked — last4 only).",
+        "operationId": "getCard",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CardId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Card details",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CardResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "patch": {
+        "tags": [
+          "Payment Cards"
+        ],
+        "summary": "Update a card's reveal policy (human-only)",
+        "operationId": "updateCard",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CardId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateCardRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Card updated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CardResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/cards/{card_id}/reveal": {
+      "post": {
+        "tags": [
+          "Payment Cards"
+        ],
+        "summary": "Reveal card details",
+        "description": "Reveal full card details (PAN/CVV or gift-card redemption). Humans must re-authenticate with their account password via the `X-Auth-Confirm` header. Agents may reveal only when a human has enabled a per-card reveal policy. Once revealed, the card can be used anywhere up to its balance — 1Claw has no further control.\n",
+        "operationId": "revealCard",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CardId"
+          },
+          {
+            "name": "X-Auth-Confirm",
+            "in": "header",
+            "required": false,
+            "description": "Account password (humans) for re-authentication.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Revealed card details (sensitive)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CardRevealResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/cards/{card_id}/void": {
+      "post": {
+        "tags": [
+          "Payment Cards"
+        ],
+        "summary": "Void a card",
+        "description": "1Claw-level lock that blocks all further reveals/refreshes. Forward-looking only — a card revealed before void remains live.",
+        "operationId": "voidCard",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CardId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Card voided",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CardResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/cards/{card_id}/refresh": {
+      "post": {
+        "tags": [
+          "Payment Cards"
+        ],
+        "summary": "Refresh a card's balance",
+        "description": "Proxy Laso refresh to update balance/status. Rate-limited to once per 5 minutes per card (429 on exceed).",
+        "operationId": "refreshCard",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CardId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Card refreshed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CardResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "429": {
+            "description": "Refreshed too recently"
+          }
+        }
+      }
     }
   },
   "components": {
@@ -10009,10 +10335,19 @@
           "format": "uuid"
         }
       },
-      "IncludeSignedTx": {
-        "name": "include_signed_tx",
-        "in": "query",
-        "required": false,
+      "CardId": {
+        "name": "card_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "IncludeSignedTx": {
+        "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. Applies to GET /v1/agents/{agent_id}/transactions and GET /v1/agents/{agent_id}/transactions/{tx_id}.\n",
         "schema": {
           "type": "boolean",
@@ -10084,6 +10419,251 @@
       }
     },
     "schemas": {
+      "OrderCardRequest": {
+        "type": "object",
+        "required": [
+          "kind",
+          "amount_usd"
+        ],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "prepaid",
+              "gift_card"
+            ]
+          },
+          "amount_usd": {
+            "type": "string",
+            "description": "USD amount to load onto the card.",
+            "example": "25.00"
+          },
+          "laso_server_id": {
+            "type": "string",
+            "description": "Optional Laso gift-card server/brand id (gift cards only)."
+          },
+          "country": {
+            "type": "string",
+            "description": "Optional country (prepaid cards; defaults to US)."
+          }
+        }
+      },
+      "CardResponse": {
+        "type": "object",
+        "description": "Masked card view — never contains PAN/CVV.",
+        "required": [
+          "id",
+          "issuer",
+          "kind",
+          "currency",
+          "status",
+          "storage_mode",
+          "reveal_policy",
+          "created_at",
+          "updated_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true
+          },
+          "issuer": {
+            "type": "string",
+            "enum": [
+              "laso",
+              "manual"
+            ]
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "prepaid",
+              "gift_card"
+            ]
+          },
+          "brand": {
+            "type": "string"
+          },
+          "last4": {
+            "type": "string"
+          },
+          "exp_month": {
+            "type": "integer"
+          },
+          "exp_year": {
+            "type": "integer"
+          },
+          "currency": {
+            "type": "string"
+          },
+          "order_amount_usd": {
+            "type": "string"
+          },
+          "balance": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "ordering",
+              "pending",
+              "ready",
+              "depleted",
+              "expired",
+              "voided",
+              "orphaned_payment"
+            ]
+          },
+          "storage_mode": {
+            "type": "string",
+            "enum": [
+              "reference",
+              "full"
+            ]
+          },
+          "reveal_policy": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "void_after": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "CardListResponse": {
+        "type": "object",
+        "required": [
+          "cards"
+        ],
+        "properties": {
+          "cards": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CardResponse"
+            }
+          }
+        }
+      },
+      "CardRevealResponse": {
+        "type": "object",
+        "description": "Revealed card details — sensitive. Returned only by the reveal endpoint.",
+        "required": [
+          "id",
+          "disclaimer"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "pan": {
+            "type": "string"
+          },
+          "cvv": {
+            "type": "string"
+          },
+          "exp_month": {
+            "type": "integer"
+          },
+          "exp_year": {
+            "type": "integer"
+          },
+          "brand": {
+            "type": "string"
+          },
+          "redemption": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Gift-card redemption payload (URL/code/PIN) when applicable."
+          },
+          "disclaimer": {
+            "type": "string"
+          }
+        }
+      },
+      "UpdateCardRequest": {
+        "type": "object",
+        "description": "Human-settable per-card reveal policy + lifecycle controls.",
+        "properties": {
+          "agent_reveal": {
+            "type": "boolean"
+          },
+          "max_reveals": {
+            "type": "integer"
+          },
+          "reveal_expires_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "void_after": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          }
+        }
+      },
+      "ImportCardRequest": {
+        "type": "object",
+        "required": [
+          "pan",
+          "cvv",
+          "exp_month",
+          "exp_year"
+        ],
+        "properties": {
+          "pan": {
+            "type": "string"
+          },
+          "cvv": {
+            "type": "string"
+          },
+          "exp_month": {
+            "type": "integer"
+          },
+          "exp_year": {
+            "type": "integer"
+          },
+          "brand": {
+            "type": "string"
+          },
+          "currency": {
+            "type": "string"
+          },
+          "balance": {
+            "type": "string"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid"
+          }
+        }
+      },
+      "SearchGiftCardsRequest": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string"
+          },
+          "country": {
+            "type": "string"
+          }
+        }
+      },
       "ProblemDetails": {
         "type": "object",
         "description": "RFC 7807 error envelope",
@@ -11405,7 +11985,50 @@
           "per_chain_guardrails": {
             "type": "object",
             "additionalProperties": true,
-            "description": "Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron).\nEach value may include max_value, daily_limit, to_allowlist, token_allowlist (legacy *_eth keys accepted).\nStrictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.\n"
+            "description": "Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron).\nEach value may include max_value, daily_limit, to_allowlist, token_allowlist, max_per_day, overhead_budget, max_ata_creates_per_day.\nStrictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.\n"
+          },
+          "tx_max_per_day": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Max transactions per UTC calendar day. Null = unlimited."
+          },
+          "tx_overhead_budget": {
+            "type": "object",
+            "nullable": true,
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Per-chain daily overhead budget in native units (e.g. {\"solana\":\"0.5\",\"xrp\":\"100\"})."
+          },
+          "solana_ata_allowlist": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Solana wallet addresses whose ATAs may be created. Empty = unrestricted."
+          },
+          "cards_enabled": {
+            "type": "boolean",
+            "description": "Whether this agent may order payment cards (x402 card ordering). Pro+ tier."
+          },
+          "card_max_order_usd": {
+            "type": "string",
+            "description": "Maximum USD amount for a single card order."
+          },
+          "card_daily_limit_usd": {
+            "type": "string",
+            "description": "Maximum cumulative USD spent ordering cards per rolling 24h window."
+          },
+          "card_payto_allowlist": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients)."
+          },
+          "card_reveal_enabled": {
+            "type": "boolean",
+            "description": "Whether agents may reveal card details subject to per-card reveal policy."
           },
           "api_key_expires_at": {
             "type": "string",
@@ -11502,6 +12125,51 @@
             "type": "boolean",
             "description": "When true, execute requests must arrive via TEE and all direct secret reads are blocked (Pro+ only)"
           },
+          "tx_max_per_day": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Max transactions per UTC calendar day. Null = unlimited."
+          },
+          "tx_overhead_budget": {
+            "type": "object",
+            "nullable": true,
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Per-chain daily overhead budget in native units."
+          },
+          "solana_ata_allowlist": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Solana wallet addresses whose ATAs may be created."
+          },
+          "cards_enabled": {
+            "type": "boolean",
+            "description": "Whether this agent may order payment cards (x402 card ordering). Pro+ tier."
+          },
+          "card_max_order_usd": {
+            "type": "string",
+            "nullable": true,
+            "description": "Maximum USD amount for a single card order. null clears."
+          },
+          "card_daily_limit_usd": {
+            "type": "string",
+            "nullable": true,
+            "description": "Maximum cumulative USD spent ordering cards per rolling 24h window. null clears."
+          },
+          "card_payto_allowlist": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients)."
+          },
+          "card_reveal_enabled": {
+            "type": "boolean",
+            "description": "Whether agents may reveal card details subject to per-card reveal policy."
+          },
           "federation_enabled": {
             "type": "boolean",
             "description": "Enable OIDC federation (RFC 8693 token-exchange) for this agent.\nWhen true, the agent may call POST /v1/auth/federated-token to mint\nfederation tokens for the audiences listed in `federation_audiences`.\n"
@@ -11689,6 +12357,60 @@
             "type": "boolean",
             "description": "When true, execute requests must arrive via TEE and all direct secret reads are blocked (Pro+ only)"
           },
+          "tx_max_per_day": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Max transactions per UTC calendar day. Null = unlimited."
+          },
+          "tx_overhead_budget": {
+            "type": "object",
+            "nullable": true,
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Per-chain daily overhead budget in native units."
+          },
+          "solana_ata_allowlist": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Solana wallet addresses whose ATAs may be created."
+          },
+          "cards_enabled": {
+            "type": "boolean",
+            "description": "Whether this agent may order payment cards (x402 card ordering)."
+          },
+          "card_max_order_usd": {
+            "type": "string",
+            "description": "Maximum USD amount for a single card order."
+          },
+          "card_daily_limit_usd": {
+            "type": "string",
+            "description": "Maximum cumulative USD spent ordering cards per rolling 24h window."
+          },
+          "card_payto_allowlist": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients)."
+          },
+          "card_reveal_enabled": {
+            "type": "boolean",
+            "description": "Whether agents may reveal card details subject to per-card reveal policy."
+          },
+          "tx_count_today": {
+            "type": "integer",
+            "description": "Today's transaction count (UTC calendar day). Present when intents_api_enabled."
+          },
+          "tx_overhead_today_by_chain": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Today's overhead spend by chain in native units."
+          },
           "federation_enabled": {
             "type": "boolean",
             "description": "Whether this agent may mint OIDC federation tokens via\nPOST /v1/auth/federated-token. False by default.\n"

package/openapi.yaml

@@ -78,6 +78,8 @@ tags:
       description: Known token registry for guardrail enforcement
     - name: Execution Intents
       description: Execute HTTP calls, queries, and more through pre-configured bindings
+    - name: Payment Cards
+      description: Order prepaid/gift cards via x402, then reveal, refresh, and void them
 
 # =============================================================================
 # PATHS
@@ -6331,6 +6333,212 @@ paths:
                 "403":
                     $ref: "#/components/responses/Forbidden"
 
+    /v1/agents/{agent_id}/cards/order:
+        post:
+            tags: [Payment Cards]
+            summary: Order a payment card (x402)
+            description: >
+                Order a prepaid or gift card for an agent. Drives the x402
+                payment flow server-side using the agent's Ethereum signing key
+                (funded with USDC on Base). Requires `cards_enabled` on the agent
+                and a Pro or higher plan. An `Idempotency-Key` header is required.
+            operationId: orderCard
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: Idempotency-Key
+                  in: header
+                  required: true
+                  schema:
+                      type: string
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/OrderCardRequest"
+            responses:
+                "201":
+                    description: Card order accepted (status pending)
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/CardResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "409":
+                    $ref: "#/components/responses/Conflict"
+
+    /v1/cards:
+        get:
+            tags: [Payment Cards]
+            summary: List payment cards
+            description: List cards for the caller (agents see only their own). Always masked (last4 only).
+            operationId: listCards
+            responses:
+                "200":
+                    description: Card list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/CardListResponse"
+
+    /v1/cards/import:
+        post:
+            tags: [Payment Cards]
+            summary: Import a card (human-only)
+            description: Manually import an existing card. Full storage mode — PAN stored encrypted, CVV as a one-time-read secret. Human-only.
+            operationId: importCard
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/ImportCardRequest"
+            responses:
+                "201":
+                    description: Card imported
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/CardResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+
+    /v1/cards/gift-cards/search:
+        post:
+            tags: [Payment Cards]
+            summary: Search gift-card brands
+            description: Search available Laso gift-card brands/servers for the org's Laso account.
+            operationId: searchGiftCards
+            requestBody:
+                required: false
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/SearchGiftCardsRequest"
+            responses:
+                "200":
+                    description: Available gift-card brands (provider-shaped payload)
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                additionalProperties: true
+
+    /v1/cards/{card_id}:
+        get:
+            tags: [Payment Cards]
+            summary: Get a payment card
+            description: Get a single card (masked — last4 only).
+            operationId: getCard
+            parameters:
+                - $ref: "#/components/parameters/CardId"
+            responses:
+                "200":
+                    description: Card details
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/CardResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+        patch:
+            tags: [Payment Cards]
+            summary: Update a card's reveal policy (human-only)
+            operationId: updateCard
+            parameters:
+                - $ref: "#/components/parameters/CardId"
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/UpdateCardRequest"
+            responses:
+                "200":
+                    description: Card updated
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/CardResponse"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/cards/{card_id}/reveal:
+        post:
+            tags: [Payment Cards]
+            summary: Reveal card details
+            description: >
+                Reveal full card details (PAN/CVV or gift-card redemption).
+                Humans must re-authenticate with their account password via the
+                `X-Auth-Confirm` header. Agents may reveal only when a human has
+                enabled a per-card reveal policy. Once revealed, the card can be
+                used anywhere up to its balance — 1Claw has no further control.
+            operationId: revealCard
+            parameters:
+                - $ref: "#/components/parameters/CardId"
+                - name: X-Auth-Confirm
+                  in: header
+                  required: false
+                  description: Account password (humans) for re-authentication.
+                  schema:
+                      type: string
+            responses:
+                "200":
+                    description: Revealed card details (sensitive)
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/CardRevealResponse"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/cards/{card_id}/void:
+        post:
+            tags: [Payment Cards]
+            summary: Void a card
+            description: 1Claw-level lock that blocks all further reveals/refreshes. Forward-looking only — a card revealed before void remains live.
+            operationId: voidCard
+            parameters:
+                - $ref: "#/components/parameters/CardId"
+            responses:
+                "200":
+                    description: Card voided
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/CardResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/cards/{card_id}/refresh:
+        post:
+            tags: [Payment Cards]
+            summary: Refresh a card's balance
+            description: Proxy Laso refresh to update balance/status. Rate-limited to once per 5 minutes per card (429 on exceed).
+            operationId: refreshCard
+            parameters:
+                - $ref: "#/components/parameters/CardId"
+            responses:
+                "200":
+                    description: Card refreshed
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/CardResponse"
+                "429":
+                    description: Refreshed too recently
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
 # =============================================================================
 # COMPONENTS
 # =============================================================================
@@ -6375,6 +6583,13 @@ components:
             schema:
                 type: string
                 format: uuid
+        CardId:
+            name: card_id
+            in: path
+            required: true
+            schema:
+                type: string
+                format: uuid
         IncludeSignedTx:
             name: include_signed_tx
             in: query
@@ -6427,6 +6642,149 @@ components:
                         $ref: "#/components/schemas/ProblemDetails"
 
     schemas:
+        OrderCardRequest:
+            type: object
+            required: [kind, amount_usd]
+            properties:
+                kind:
+                    type: string
+                    enum: [prepaid, gift_card]
+                amount_usd:
+                    type: string
+                    description: USD amount to load onto the card.
+                    example: "25.00"
+                laso_server_id:
+                    type: string
+                    description: Optional Laso gift-card server/brand id (gift cards only).
+                country:
+                    type: string
+                    description: Optional country (prepaid cards; defaults to US).
+        CardResponse:
+            type: object
+            description: Masked card view — never contains PAN/CVV.
+            required: [id, issuer, kind, currency, status, storage_mode, reveal_policy, created_at, updated_at]
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                agent_id:
+                    type: string
+                    format: uuid
+                    nullable: true
+                issuer:
+                    type: string
+                    enum: [laso, manual]
+                kind:
+                    type: string
+                    enum: [prepaid, gift_card]
+                brand:
+                    type: string
+                last4:
+                    type: string
+                exp_month:
+                    type: integer
+                exp_year:
+                    type: integer
+                currency:
+                    type: string
+                order_amount_usd:
+                    type: string
+                balance:
+                    type: string
+                status:
+                    type: string
+                    enum: [ordering, pending, ready, depleted, expired, voided, orphaned_payment]
+                storage_mode:
+                    type: string
+                    enum: [reference, full]
+                reveal_policy:
+                    type: object
+                    additionalProperties: true
+                void_after:
+                    type: string
+                    format: date-time
+                created_at:
+                    type: string
+                    format: date-time
+                updated_at:
+                    type: string
+                    format: date-time
+        CardListResponse:
+            type: object
+            required: [cards]
+            properties:
+                cards:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/CardResponse"
+        CardRevealResponse:
+            type: object
+            description: Revealed card details — sensitive. Returned only by the reveal endpoint.
+            required: [id, disclaimer]
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                pan:
+                    type: string
+                cvv:
+                    type: string
+                exp_month:
+                    type: integer
+                exp_year:
+                    type: integer
+                brand:
+                    type: string
+                redemption:
+                    type: object
+                    additionalProperties: true
+                    description: Gift-card redemption payload (URL/code/PIN) when applicable.
+                disclaimer:
+                    type: string
+        UpdateCardRequest:
+            type: object
+            description: Human-settable per-card reveal policy + lifecycle controls.
+            properties:
+                agent_reveal:
+                    type: boolean
+                max_reveals:
+                    type: integer
+                reveal_expires_at:
+                    type: string
+                    format: date-time
+                    nullable: true
+                void_after:
+                    type: string
+                    format: date-time
+                    nullable: true
+        ImportCardRequest:
+            type: object
+            required: [pan, cvv, exp_month, exp_year]
+            properties:
+                pan:
+                    type: string
+                cvv:
+                    type: string
+                exp_month:
+                    type: integer
+                exp_year:
+                    type: integer
+                brand:
+                    type: string
+                currency:
+                    type: string
+                balance:
+                    type: string
+                agent_id:
+                    type: string
+                    format: uuid
+        SearchGiftCardsRequest:
+            type: object
+            properties:
+                query:
+                    type: string
+                country:
+                    type: string
         ProblemDetails:
             type: object
             description: RFC 7807 error envelope
@@ -7359,8 +7717,40 @@ components:
                     additionalProperties: true
                     description: |
                         Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron).
-                        Each value may include max_value, daily_limit, to_allowlist, token_allowlist (legacy *_eth keys accepted).
+                        Each value may include max_value, daily_limit, to_allowlist, token_allowlist, max_per_day, overhead_budget, max_ata_creates_per_day.
                         Strictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.
+                tx_max_per_day:
+                    type: integer
+                    nullable: true
+                    description: Max transactions per UTC calendar day. Null = unlimited.
+                tx_overhead_budget:
+                    type: object
+                    nullable: true
+                    additionalProperties:
+                        type: string
+                    description: Per-chain daily overhead budget in native units (e.g. {"solana":"0.5","xrp":"100"}).
+                solana_ata_allowlist:
+                    type: array
+                    items:
+                        type: string
+                    description: Solana wallet addresses whose ATAs may be created. Empty = unrestricted.
+                cards_enabled:
+                    type: boolean
+                    description: Whether this agent may order payment cards (x402 card ordering). Pro+ tier.
+                card_max_order_usd:
+                    type: string
+                    description: Maximum USD amount for a single card order.
+                card_daily_limit_usd:
+                    type: string
+                    description: Maximum cumulative USD spent ordering cards per rolling 24h window.
+                card_payto_allowlist:
+                    type: array
+                    items:
+                        type: string
+                    description: Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients).
+                card_reveal_enabled:
+                    type: boolean
+                    description: Whether agents may reveal card details subject to per-card reveal policy.
                 api_key_expires_at:
                     type: string
                     format: date-time
@@ -7431,6 +7821,40 @@ components:
                 execution_require_tee:
                     type: boolean
                     description: When true, execute requests must arrive via TEE and all direct secret reads are blocked (Pro+ only)
+                tx_max_per_day:
+                    type: integer
+                    nullable: true
+                    description: Max transactions per UTC calendar day. Null = unlimited.
+                tx_overhead_budget:
+                    type: object
+                    nullable: true
+                    additionalProperties:
+                        type: string
+                    description: Per-chain daily overhead budget in native units.
+                solana_ata_allowlist:
+                    type: array
+                    items:
+                        type: string
+                    description: Solana wallet addresses whose ATAs may be created.
+                cards_enabled:
+                    type: boolean
+                    description: Whether this agent may order payment cards (x402 card ordering). Pro+ tier.
+                card_max_order_usd:
+                    type: string
+                    nullable: true
+                    description: Maximum USD amount for a single card order. null clears.
+                card_daily_limit_usd:
+                    type: string
+                    nullable: true
+                    description: Maximum cumulative USD spent ordering cards per rolling 24h window. null clears.
+                card_payto_allowlist:
+                    type: array
+                    items:
+                        type: string
+                    description: Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients).
+                card_reveal_enabled:
+                    type: boolean
+                    description: Whether agents may reveal card details subject to per-card reveal policy.
                 federation_enabled:
                     type: boolean
                     description: |
@@ -7583,6 +8007,46 @@ components:
                 execution_require_tee:
                     type: boolean
                     description: When true, execute requests must arrive via TEE and all direct secret reads are blocked (Pro+ only)
+                tx_max_per_day:
+                    type: integer
+                    nullable: true
+                    description: Max transactions per UTC calendar day. Null = unlimited.
+                tx_overhead_budget:
+                    type: object
+                    nullable: true
+                    additionalProperties:
+                        type: string
+                    description: Per-chain daily overhead budget in native units.
+                solana_ata_allowlist:
+                    type: array
+                    items:
+                        type: string
+                    description: Solana wallet addresses whose ATAs may be created.
+                cards_enabled:
+                    type: boolean
+                    description: Whether this agent may order payment cards (x402 card ordering).
+                card_max_order_usd:
+                    type: string
+                    description: Maximum USD amount for a single card order.
+                card_daily_limit_usd:
+                    type: string
+                    description: Maximum cumulative USD spent ordering cards per rolling 24h window.
+                card_payto_allowlist:
+                    type: array
+                    items:
+                        type: string
+                    description: Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients).
+                card_reveal_enabled:
+                    type: boolean
+                    description: Whether agents may reveal card details subject to per-card reveal policy.
+                tx_count_today:
+                    type: integer
+                    description: Today's transaction count (UTC calendar day). Present when intents_api_enabled.
+                tx_overhead_today_by_chain:
+                    type: object
+                    additionalProperties:
+                        type: string
+                    description: Today's overhead spend by chain in native units.
                 federation_enabled:
                     type: boolean
                     description: |

package/package.json

@@ -1,40 +1,40 @@
 {
-    "name": "@1claw/openapi-spec",
-    "version": "0.41.1",
-    "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API — generate clients in any language",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/1clawAI/1claw.git",
-        "directory": "packages/openapi-spec"
-    },
-    "files": [
-        "openapi.yaml",
-        "openapi.json",
-        "README.md"
-    ],
-    "exports": {
-        "./openapi.yaml": "./openapi.yaml",
-        "./openapi.json": "./openapi.json"
-    },
-    "scripts": {
-        "build": "node scripts/yaml-to-json.mjs",
-        "prepublishOnly": "npm run build"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "keywords": [
-        "1claw",
-        "openapi",
-        "api-spec",
-        "codegen",
-        "swagger",
-        "secrets",
-        "vault",
-        "ai-agents"
-    ],
-    "devDependencies": {
-        "js-yaml": "^4.1.1"
-    }
+  "name": "@1claw/openapi-spec",
+  "version": "0.41.3",
+  "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API \u2014 generate clients in any language",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/1clawAI/1claw.git",
+    "directory": "packages/openapi-spec"
+  },
+  "files": [
+    "openapi.yaml",
+    "openapi.json",
+    "README.md"
+  ],
+  "exports": {
+    "./openapi.yaml": "./openapi.yaml",
+    "./openapi.json": "./openapi.json"
+  },
+  "scripts": {
+    "build": "node scripts/yaml-to-json.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "1claw",
+    "openapi",
+    "api-spec",
+    "codegen",
+    "swagger",
+    "secrets",
+    "vault",
+    "ai-agents"
+  ],
+  "devDependencies": {
+    "js-yaml": "^4.1.1"
+  }
 }