@1claw/openapi-spec 0.41.2 → 0.41.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/openapi.json +651 -0
  2. package/openapi.yaml +411 -0
  3. package/package.json +38 -38
package/openapi.json CHANGED
@@ -130,6 +130,10 @@
130
130
  {
131
131
  "name": "Execution Intents",
132
132
  "description": "Execute HTTP calls, queries, and more through pre-configured bindings"
133
+ },
134
+ {
135
+ "name": "Payment Cards",
136
+ "description": "Order prepaid/gift cards via x402, then reveal, refresh, and void them"
133
137
  }
134
138
  ],
135
139
  "paths": {
@@ -9957,6 +9961,328 @@
9957
9961
  }
9958
9962
  }
9959
9963
  }
9964
+ },
9965
+ "/v1/agents/{agent_id}/cards/order": {
9966
+ "post": {
9967
+ "tags": [
9968
+ "Payment Cards"
9969
+ ],
9970
+ "summary": "Order a payment card (x402)",
9971
+ "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",
9972
+ "operationId": "orderCard",
9973
+ "parameters": [
9974
+ {
9975
+ "$ref": "#/components/parameters/AgentId"
9976
+ },
9977
+ {
9978
+ "name": "Idempotency-Key",
9979
+ "in": "header",
9980
+ "required": true,
9981
+ "schema": {
9982
+ "type": "string"
9983
+ }
9984
+ }
9985
+ ],
9986
+ "requestBody": {
9987
+ "required": true,
9988
+ "content": {
9989
+ "application/json": {
9990
+ "schema": {
9991
+ "$ref": "#/components/schemas/OrderCardRequest"
9992
+ }
9993
+ }
9994
+ }
9995
+ },
9996
+ "responses": {
9997
+ "201": {
9998
+ "description": "Card order accepted (status pending)",
9999
+ "content": {
10000
+ "application/json": {
10001
+ "schema": {
10002
+ "$ref": "#/components/schemas/CardResponse"
10003
+ }
10004
+ }
10005
+ }
10006
+ },
10007
+ "400": {
10008
+ "$ref": "#/components/responses/BadRequest"
10009
+ },
10010
+ "403": {
10011
+ "$ref": "#/components/responses/Forbidden"
10012
+ },
10013
+ "409": {
10014
+ "$ref": "#/components/responses/Conflict"
10015
+ }
10016
+ }
10017
+ }
10018
+ },
10019
+ "/v1/cards": {
10020
+ "get": {
10021
+ "tags": [
10022
+ "Payment Cards"
10023
+ ],
10024
+ "summary": "List payment cards",
10025
+ "description": "List cards for the caller (agents see only their own). Always masked (last4 only).",
10026
+ "operationId": "listCards",
10027
+ "responses": {
10028
+ "200": {
10029
+ "description": "Card list",
10030
+ "content": {
10031
+ "application/json": {
10032
+ "schema": {
10033
+ "$ref": "#/components/schemas/CardListResponse"
10034
+ }
10035
+ }
10036
+ }
10037
+ }
10038
+ }
10039
+ }
10040
+ },
10041
+ "/v1/cards/import": {
10042
+ "post": {
10043
+ "tags": [
10044
+ "Payment Cards"
10045
+ ],
10046
+ "summary": "Import a card (human-only)",
10047
+ "description": "Manually import an existing card. Full storage mode — PAN stored encrypted, CVV as a one-time-read secret. Human-only.",
10048
+ "operationId": "importCard",
10049
+ "requestBody": {
10050
+ "required": true,
10051
+ "content": {
10052
+ "application/json": {
10053
+ "schema": {
10054
+ "$ref": "#/components/schemas/ImportCardRequest"
10055
+ }
10056
+ }
10057
+ }
10058
+ },
10059
+ "responses": {
10060
+ "201": {
10061
+ "description": "Card imported",
10062
+ "content": {
10063
+ "application/json": {
10064
+ "schema": {
10065
+ "$ref": "#/components/schemas/CardResponse"
10066
+ }
10067
+ }
10068
+ }
10069
+ },
10070
+ "400": {
10071
+ "$ref": "#/components/responses/BadRequest"
10072
+ },
10073
+ "403": {
10074
+ "$ref": "#/components/responses/Forbidden"
10075
+ }
10076
+ }
10077
+ }
10078
+ },
10079
+ "/v1/cards/gift-cards/search": {
10080
+ "post": {
10081
+ "tags": [
10082
+ "Payment Cards"
10083
+ ],
10084
+ "summary": "Search gift-card brands",
10085
+ "description": "Search available Laso gift-card brands/servers for the org's Laso account.",
10086
+ "operationId": "searchGiftCards",
10087
+ "requestBody": {
10088
+ "required": false,
10089
+ "content": {
10090
+ "application/json": {
10091
+ "schema": {
10092
+ "$ref": "#/components/schemas/SearchGiftCardsRequest"
10093
+ }
10094
+ }
10095
+ }
10096
+ },
10097
+ "responses": {
10098
+ "200": {
10099
+ "description": "Available gift-card brands (provider-shaped payload)",
10100
+ "content": {
10101
+ "application/json": {
10102
+ "schema": {
10103
+ "type": "object",
10104
+ "additionalProperties": true
10105
+ }
10106
+ }
10107
+ }
10108
+ }
10109
+ }
10110
+ }
10111
+ },
10112
+ "/v1/cards/{card_id}": {
10113
+ "get": {
10114
+ "tags": [
10115
+ "Payment Cards"
10116
+ ],
10117
+ "summary": "Get a payment card",
10118
+ "description": "Get a single card (masked — last4 only).",
10119
+ "operationId": "getCard",
10120
+ "parameters": [
10121
+ {
10122
+ "$ref": "#/components/parameters/CardId"
10123
+ }
10124
+ ],
10125
+ "responses": {
10126
+ "200": {
10127
+ "description": "Card details",
10128
+ "content": {
10129
+ "application/json": {
10130
+ "schema": {
10131
+ "$ref": "#/components/schemas/CardResponse"
10132
+ }
10133
+ }
10134
+ }
10135
+ },
10136
+ "404": {
10137
+ "$ref": "#/components/responses/NotFound"
10138
+ }
10139
+ }
10140
+ },
10141
+ "patch": {
10142
+ "tags": [
10143
+ "Payment Cards"
10144
+ ],
10145
+ "summary": "Update a card's reveal policy (human-only)",
10146
+ "operationId": "updateCard",
10147
+ "parameters": [
10148
+ {
10149
+ "$ref": "#/components/parameters/CardId"
10150
+ }
10151
+ ],
10152
+ "requestBody": {
10153
+ "required": true,
10154
+ "content": {
10155
+ "application/json": {
10156
+ "schema": {
10157
+ "$ref": "#/components/schemas/UpdateCardRequest"
10158
+ }
10159
+ }
10160
+ }
10161
+ },
10162
+ "responses": {
10163
+ "200": {
10164
+ "description": "Card updated",
10165
+ "content": {
10166
+ "application/json": {
10167
+ "schema": {
10168
+ "$ref": "#/components/schemas/CardResponse"
10169
+ }
10170
+ }
10171
+ }
10172
+ },
10173
+ "403": {
10174
+ "$ref": "#/components/responses/Forbidden"
10175
+ },
10176
+ "404": {
10177
+ "$ref": "#/components/responses/NotFound"
10178
+ }
10179
+ }
10180
+ }
10181
+ },
10182
+ "/v1/cards/{card_id}/reveal": {
10183
+ "post": {
10184
+ "tags": [
10185
+ "Payment Cards"
10186
+ ],
10187
+ "summary": "Reveal card details",
10188
+ "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",
10189
+ "operationId": "revealCard",
10190
+ "parameters": [
10191
+ {
10192
+ "$ref": "#/components/parameters/CardId"
10193
+ },
10194
+ {
10195
+ "name": "X-Auth-Confirm",
10196
+ "in": "header",
10197
+ "required": false,
10198
+ "description": "Account password (humans) for re-authentication.",
10199
+ "schema": {
10200
+ "type": "string"
10201
+ }
10202
+ }
10203
+ ],
10204
+ "responses": {
10205
+ "200": {
10206
+ "description": "Revealed card details (sensitive)",
10207
+ "content": {
10208
+ "application/json": {
10209
+ "schema": {
10210
+ "$ref": "#/components/schemas/CardRevealResponse"
10211
+ }
10212
+ }
10213
+ }
10214
+ },
10215
+ "403": {
10216
+ "$ref": "#/components/responses/Forbidden"
10217
+ },
10218
+ "404": {
10219
+ "$ref": "#/components/responses/NotFound"
10220
+ }
10221
+ }
10222
+ }
10223
+ },
10224
+ "/v1/cards/{card_id}/void": {
10225
+ "post": {
10226
+ "tags": [
10227
+ "Payment Cards"
10228
+ ],
10229
+ "summary": "Void a card",
10230
+ "description": "1Claw-level lock that blocks all further reveals/refreshes. Forward-looking only — a card revealed before void remains live.",
10231
+ "operationId": "voidCard",
10232
+ "parameters": [
10233
+ {
10234
+ "$ref": "#/components/parameters/CardId"
10235
+ }
10236
+ ],
10237
+ "responses": {
10238
+ "200": {
10239
+ "description": "Card voided",
10240
+ "content": {
10241
+ "application/json": {
10242
+ "schema": {
10243
+ "$ref": "#/components/schemas/CardResponse"
10244
+ }
10245
+ }
10246
+ }
10247
+ },
10248
+ "404": {
10249
+ "$ref": "#/components/responses/NotFound"
10250
+ }
10251
+ }
10252
+ }
10253
+ },
10254
+ "/v1/cards/{card_id}/refresh": {
10255
+ "post": {
10256
+ "tags": [
10257
+ "Payment Cards"
10258
+ ],
10259
+ "summary": "Refresh a card's balance",
10260
+ "description": "Proxy Laso refresh to update balance/status. Rate-limited to once per 5 minutes per card (429 on exceed).",
10261
+ "operationId": "refreshCard",
10262
+ "parameters": [
10263
+ {
10264
+ "$ref": "#/components/parameters/CardId"
10265
+ }
10266
+ ],
10267
+ "responses": {
10268
+ "200": {
10269
+ "description": "Card refreshed",
10270
+ "content": {
10271
+ "application/json": {
10272
+ "schema": {
10273
+ "$ref": "#/components/schemas/CardResponse"
10274
+ }
10275
+ }
10276
+ }
10277
+ },
10278
+ "404": {
10279
+ "$ref": "#/components/responses/NotFound"
10280
+ },
10281
+ "429": {
10282
+ "description": "Refreshed too recently"
10283
+ }
10284
+ }
10285
+ }
9960
10286
  }
9961
10287
  },
9962
10288
  "components": {
@@ -10009,6 +10335,15 @@
10009
10335
  "format": "uuid"
10010
10336
  }
10011
10337
  },
10338
+ "CardId": {
10339
+ "name": "card_id",
10340
+ "in": "path",
10341
+ "required": true,
10342
+ "schema": {
10343
+ "type": "string",
10344
+ "format": "uuid"
10345
+ }
10346
+ },
10012
10347
  "IncludeSignedTx": {
10013
10348
  "name": "include_signed_tx",
10014
10349
  "in": "query",
@@ -10084,6 +10419,251 @@
10084
10419
  }
10085
10420
  },
10086
10421
  "schemas": {
10422
+ "OrderCardRequest": {
10423
+ "type": "object",
10424
+ "required": [
10425
+ "kind",
10426
+ "amount_usd"
10427
+ ],
10428
+ "properties": {
10429
+ "kind": {
10430
+ "type": "string",
10431
+ "enum": [
10432
+ "prepaid",
10433
+ "gift_card"
10434
+ ]
10435
+ },
10436
+ "amount_usd": {
10437
+ "type": "string",
10438
+ "description": "USD amount to load onto the card.",
10439
+ "example": "25.00"
10440
+ },
10441
+ "laso_server_id": {
10442
+ "type": "string",
10443
+ "description": "Optional Laso gift-card server/brand id (gift cards only)."
10444
+ },
10445
+ "country": {
10446
+ "type": "string",
10447
+ "description": "Optional country (prepaid cards; defaults to US)."
10448
+ }
10449
+ }
10450
+ },
10451
+ "CardResponse": {
10452
+ "type": "object",
10453
+ "description": "Masked card view — never contains PAN/CVV.",
10454
+ "required": [
10455
+ "id",
10456
+ "issuer",
10457
+ "kind",
10458
+ "currency",
10459
+ "status",
10460
+ "storage_mode",
10461
+ "reveal_policy",
10462
+ "created_at",
10463
+ "updated_at"
10464
+ ],
10465
+ "properties": {
10466
+ "id": {
10467
+ "type": "string",
10468
+ "format": "uuid"
10469
+ },
10470
+ "agent_id": {
10471
+ "type": "string",
10472
+ "format": "uuid",
10473
+ "nullable": true
10474
+ },
10475
+ "issuer": {
10476
+ "type": "string",
10477
+ "enum": [
10478
+ "laso",
10479
+ "manual"
10480
+ ]
10481
+ },
10482
+ "kind": {
10483
+ "type": "string",
10484
+ "enum": [
10485
+ "prepaid",
10486
+ "gift_card"
10487
+ ]
10488
+ },
10489
+ "brand": {
10490
+ "type": "string"
10491
+ },
10492
+ "last4": {
10493
+ "type": "string"
10494
+ },
10495
+ "exp_month": {
10496
+ "type": "integer"
10497
+ },
10498
+ "exp_year": {
10499
+ "type": "integer"
10500
+ },
10501
+ "currency": {
10502
+ "type": "string"
10503
+ },
10504
+ "order_amount_usd": {
10505
+ "type": "string"
10506
+ },
10507
+ "balance": {
10508
+ "type": "string"
10509
+ },
10510
+ "status": {
10511
+ "type": "string",
10512
+ "enum": [
10513
+ "ordering",
10514
+ "pending",
10515
+ "ready",
10516
+ "depleted",
10517
+ "expired",
10518
+ "voided",
10519
+ "orphaned_payment"
10520
+ ]
10521
+ },
10522
+ "storage_mode": {
10523
+ "type": "string",
10524
+ "enum": [
10525
+ "reference",
10526
+ "full"
10527
+ ]
10528
+ },
10529
+ "reveal_policy": {
10530
+ "type": "object",
10531
+ "additionalProperties": true
10532
+ },
10533
+ "void_after": {
10534
+ "type": "string",
10535
+ "format": "date-time"
10536
+ },
10537
+ "created_at": {
10538
+ "type": "string",
10539
+ "format": "date-time"
10540
+ },
10541
+ "updated_at": {
10542
+ "type": "string",
10543
+ "format": "date-time"
10544
+ }
10545
+ }
10546
+ },
10547
+ "CardListResponse": {
10548
+ "type": "object",
10549
+ "required": [
10550
+ "cards"
10551
+ ],
10552
+ "properties": {
10553
+ "cards": {
10554
+ "type": "array",
10555
+ "items": {
10556
+ "$ref": "#/components/schemas/CardResponse"
10557
+ }
10558
+ }
10559
+ }
10560
+ },
10561
+ "CardRevealResponse": {
10562
+ "type": "object",
10563
+ "description": "Revealed card details — sensitive. Returned only by the reveal endpoint.",
10564
+ "required": [
10565
+ "id",
10566
+ "disclaimer"
10567
+ ],
10568
+ "properties": {
10569
+ "id": {
10570
+ "type": "string",
10571
+ "format": "uuid"
10572
+ },
10573
+ "pan": {
10574
+ "type": "string"
10575
+ },
10576
+ "cvv": {
10577
+ "type": "string"
10578
+ },
10579
+ "exp_month": {
10580
+ "type": "integer"
10581
+ },
10582
+ "exp_year": {
10583
+ "type": "integer"
10584
+ },
10585
+ "brand": {
10586
+ "type": "string"
10587
+ },
10588
+ "redemption": {
10589
+ "type": "object",
10590
+ "additionalProperties": true,
10591
+ "description": "Gift-card redemption payload (URL/code/PIN) when applicable."
10592
+ },
10593
+ "disclaimer": {
10594
+ "type": "string"
10595
+ }
10596
+ }
10597
+ },
10598
+ "UpdateCardRequest": {
10599
+ "type": "object",
10600
+ "description": "Human-settable per-card reveal policy + lifecycle controls.",
10601
+ "properties": {
10602
+ "agent_reveal": {
10603
+ "type": "boolean"
10604
+ },
10605
+ "max_reveals": {
10606
+ "type": "integer"
10607
+ },
10608
+ "reveal_expires_at": {
10609
+ "type": "string",
10610
+ "format": "date-time",
10611
+ "nullable": true
10612
+ },
10613
+ "void_after": {
10614
+ "type": "string",
10615
+ "format": "date-time",
10616
+ "nullable": true
10617
+ }
10618
+ }
10619
+ },
10620
+ "ImportCardRequest": {
10621
+ "type": "object",
10622
+ "required": [
10623
+ "pan",
10624
+ "cvv",
10625
+ "exp_month",
10626
+ "exp_year"
10627
+ ],
10628
+ "properties": {
10629
+ "pan": {
10630
+ "type": "string"
10631
+ },
10632
+ "cvv": {
10633
+ "type": "string"
10634
+ },
10635
+ "exp_month": {
10636
+ "type": "integer"
10637
+ },
10638
+ "exp_year": {
10639
+ "type": "integer"
10640
+ },
10641
+ "brand": {
10642
+ "type": "string"
10643
+ },
10644
+ "currency": {
10645
+ "type": "string"
10646
+ },
10647
+ "balance": {
10648
+ "type": "string"
10649
+ },
10650
+ "agent_id": {
10651
+ "type": "string",
10652
+ "format": "uuid"
10653
+ }
10654
+ }
10655
+ },
10656
+ "SearchGiftCardsRequest": {
10657
+ "type": "object",
10658
+ "properties": {
10659
+ "query": {
10660
+ "type": "string"
10661
+ },
10662
+ "country": {
10663
+ "type": "string"
10664
+ }
10665
+ }
10666
+ },
10087
10667
  "ProblemDetails": {
10088
10668
  "type": "object",
10089
10669
  "description": "RFC 7807 error envelope",
@@ -11427,6 +12007,29 @@
11427
12007
  },
11428
12008
  "description": "Solana wallet addresses whose ATAs may be created. Empty = unrestricted."
11429
12009
  },
12010
+ "cards_enabled": {
12011
+ "type": "boolean",
12012
+ "description": "Whether this agent may order payment cards (x402 card ordering). Pro+ tier."
12013
+ },
12014
+ "card_max_order_usd": {
12015
+ "type": "string",
12016
+ "description": "Maximum USD amount for a single card order."
12017
+ },
12018
+ "card_daily_limit_usd": {
12019
+ "type": "string",
12020
+ "description": "Maximum cumulative USD spent ordering cards per rolling 24h window."
12021
+ },
12022
+ "card_payto_allowlist": {
12023
+ "type": "array",
12024
+ "items": {
12025
+ "type": "string"
12026
+ },
12027
+ "description": "Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients)."
12028
+ },
12029
+ "card_reveal_enabled": {
12030
+ "type": "boolean",
12031
+ "description": "Whether agents may reveal card details subject to per-card reveal policy."
12032
+ },
11430
12033
  "api_key_expires_at": {
11431
12034
  "type": "string",
11432
12035
  "format": "date-time",
@@ -11542,6 +12145,31 @@
11542
12145
  },
11543
12146
  "description": "Solana wallet addresses whose ATAs may be created."
11544
12147
  },
12148
+ "cards_enabled": {
12149
+ "type": "boolean",
12150
+ "description": "Whether this agent may order payment cards (x402 card ordering). Pro+ tier."
12151
+ },
12152
+ "card_max_order_usd": {
12153
+ "type": "string",
12154
+ "nullable": true,
12155
+ "description": "Maximum USD amount for a single card order. null clears."
12156
+ },
12157
+ "card_daily_limit_usd": {
12158
+ "type": "string",
12159
+ "nullable": true,
12160
+ "description": "Maximum cumulative USD spent ordering cards per rolling 24h window. null clears."
12161
+ },
12162
+ "card_payto_allowlist": {
12163
+ "type": "array",
12164
+ "items": {
12165
+ "type": "string"
12166
+ },
12167
+ "description": "Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients)."
12168
+ },
12169
+ "card_reveal_enabled": {
12170
+ "type": "boolean",
12171
+ "description": "Whether agents may reveal card details subject to per-card reveal policy."
12172
+ },
11545
12173
  "federation_enabled": {
11546
12174
  "type": "boolean",
11547
12175
  "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"
@@ -11749,6 +12377,29 @@
11749
12377
  },
11750
12378
  "description": "Solana wallet addresses whose ATAs may be created."
11751
12379
  },
12380
+ "cards_enabled": {
12381
+ "type": "boolean",
12382
+ "description": "Whether this agent may order payment cards (x402 card ordering)."
12383
+ },
12384
+ "card_max_order_usd": {
12385
+ "type": "string",
12386
+ "description": "Maximum USD amount for a single card order."
12387
+ },
12388
+ "card_daily_limit_usd": {
12389
+ "type": "string",
12390
+ "description": "Maximum cumulative USD spent ordering cards per rolling 24h window."
12391
+ },
12392
+ "card_payto_allowlist": {
12393
+ "type": "array",
12394
+ "items": {
12395
+ "type": "string"
12396
+ },
12397
+ "description": "Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients)."
12398
+ },
12399
+ "card_reveal_enabled": {
12400
+ "type": "boolean",
12401
+ "description": "Whether agents may reveal card details subject to per-card reveal policy."
12402
+ },
11752
12403
  "tx_count_today": {
11753
12404
  "type": "integer",
11754
12405
  "description": "Today's transaction count (UTC calendar day). Present when intents_api_enabled."
package/openapi.yaml CHANGED
@@ -78,6 +78,8 @@ tags:
78
78
  description: Known token registry for guardrail enforcement
79
79
  - name: Execution Intents
80
80
  description: Execute HTTP calls, queries, and more through pre-configured bindings
81
+ - name: Payment Cards
82
+ description: Order prepaid/gift cards via x402, then reveal, refresh, and void them
81
83
 
82
84
  # =============================================================================
83
85
  # PATHS
@@ -6331,6 +6333,212 @@ paths:
6331
6333
  "403":
6332
6334
  $ref: "#/components/responses/Forbidden"
6333
6335
 
6336
+ /v1/agents/{agent_id}/cards/order:
6337
+ post:
6338
+ tags: [Payment Cards]
6339
+ summary: Order a payment card (x402)
6340
+ description: >
6341
+ Order a prepaid or gift card for an agent. Drives the x402
6342
+ payment flow server-side using the agent's Ethereum signing key
6343
+ (funded with USDC on Base). Requires `cards_enabled` on the agent
6344
+ and a Pro or higher plan. An `Idempotency-Key` header is required.
6345
+ operationId: orderCard
6346
+ parameters:
6347
+ - $ref: "#/components/parameters/AgentId"
6348
+ - name: Idempotency-Key
6349
+ in: header
6350
+ required: true
6351
+ schema:
6352
+ type: string
6353
+ requestBody:
6354
+ required: true
6355
+ content:
6356
+ application/json:
6357
+ schema:
6358
+ $ref: "#/components/schemas/OrderCardRequest"
6359
+ responses:
6360
+ "201":
6361
+ description: Card order accepted (status pending)
6362
+ content:
6363
+ application/json:
6364
+ schema:
6365
+ $ref: "#/components/schemas/CardResponse"
6366
+ "400":
6367
+ $ref: "#/components/responses/BadRequest"
6368
+ "403":
6369
+ $ref: "#/components/responses/Forbidden"
6370
+ "409":
6371
+ $ref: "#/components/responses/Conflict"
6372
+
6373
+ /v1/cards:
6374
+ get:
6375
+ tags: [Payment Cards]
6376
+ summary: List payment cards
6377
+ description: List cards for the caller (agents see only their own). Always masked (last4 only).
6378
+ operationId: listCards
6379
+ responses:
6380
+ "200":
6381
+ description: Card list
6382
+ content:
6383
+ application/json:
6384
+ schema:
6385
+ $ref: "#/components/schemas/CardListResponse"
6386
+
6387
+ /v1/cards/import:
6388
+ post:
6389
+ tags: [Payment Cards]
6390
+ summary: Import a card (human-only)
6391
+ description: Manually import an existing card. Full storage mode — PAN stored encrypted, CVV as a one-time-read secret. Human-only.
6392
+ operationId: importCard
6393
+ requestBody:
6394
+ required: true
6395
+ content:
6396
+ application/json:
6397
+ schema:
6398
+ $ref: "#/components/schemas/ImportCardRequest"
6399
+ responses:
6400
+ "201":
6401
+ description: Card imported
6402
+ content:
6403
+ application/json:
6404
+ schema:
6405
+ $ref: "#/components/schemas/CardResponse"
6406
+ "400":
6407
+ $ref: "#/components/responses/BadRequest"
6408
+ "403":
6409
+ $ref: "#/components/responses/Forbidden"
6410
+
6411
+ /v1/cards/gift-cards/search:
6412
+ post:
6413
+ tags: [Payment Cards]
6414
+ summary: Search gift-card brands
6415
+ description: Search available Laso gift-card brands/servers for the org's Laso account.
6416
+ operationId: searchGiftCards
6417
+ requestBody:
6418
+ required: false
6419
+ content:
6420
+ application/json:
6421
+ schema:
6422
+ $ref: "#/components/schemas/SearchGiftCardsRequest"
6423
+ responses:
6424
+ "200":
6425
+ description: Available gift-card brands (provider-shaped payload)
6426
+ content:
6427
+ application/json:
6428
+ schema:
6429
+ type: object
6430
+ additionalProperties: true
6431
+
6432
+ /v1/cards/{card_id}:
6433
+ get:
6434
+ tags: [Payment Cards]
6435
+ summary: Get a payment card
6436
+ description: Get a single card (masked — last4 only).
6437
+ operationId: getCard
6438
+ parameters:
6439
+ - $ref: "#/components/parameters/CardId"
6440
+ responses:
6441
+ "200":
6442
+ description: Card details
6443
+ content:
6444
+ application/json:
6445
+ schema:
6446
+ $ref: "#/components/schemas/CardResponse"
6447
+ "404":
6448
+ $ref: "#/components/responses/NotFound"
6449
+ patch:
6450
+ tags: [Payment Cards]
6451
+ summary: Update a card's reveal policy (human-only)
6452
+ operationId: updateCard
6453
+ parameters:
6454
+ - $ref: "#/components/parameters/CardId"
6455
+ requestBody:
6456
+ required: true
6457
+ content:
6458
+ application/json:
6459
+ schema:
6460
+ $ref: "#/components/schemas/UpdateCardRequest"
6461
+ responses:
6462
+ "200":
6463
+ description: Card updated
6464
+ content:
6465
+ application/json:
6466
+ schema:
6467
+ $ref: "#/components/schemas/CardResponse"
6468
+ "403":
6469
+ $ref: "#/components/responses/Forbidden"
6470
+ "404":
6471
+ $ref: "#/components/responses/NotFound"
6472
+
6473
+ /v1/cards/{card_id}/reveal:
6474
+ post:
6475
+ tags: [Payment Cards]
6476
+ summary: Reveal card details
6477
+ description: >
6478
+ Reveal full card details (PAN/CVV or gift-card redemption).
6479
+ Humans must re-authenticate with their account password via the
6480
+ `X-Auth-Confirm` header. Agents may reveal only when a human has
6481
+ enabled a per-card reveal policy. Once revealed, the card can be
6482
+ used anywhere up to its balance — 1Claw has no further control.
6483
+ operationId: revealCard
6484
+ parameters:
6485
+ - $ref: "#/components/parameters/CardId"
6486
+ - name: X-Auth-Confirm
6487
+ in: header
6488
+ required: false
6489
+ description: Account password (humans) for re-authentication.
6490
+ schema:
6491
+ type: string
6492
+ responses:
6493
+ "200":
6494
+ description: Revealed card details (sensitive)
6495
+ content:
6496
+ application/json:
6497
+ schema:
6498
+ $ref: "#/components/schemas/CardRevealResponse"
6499
+ "403":
6500
+ $ref: "#/components/responses/Forbidden"
6501
+ "404":
6502
+ $ref: "#/components/responses/NotFound"
6503
+
6504
+ /v1/cards/{card_id}/void:
6505
+ post:
6506
+ tags: [Payment Cards]
6507
+ summary: Void a card
6508
+ description: 1Claw-level lock that blocks all further reveals/refreshes. Forward-looking only — a card revealed before void remains live.
6509
+ operationId: voidCard
6510
+ parameters:
6511
+ - $ref: "#/components/parameters/CardId"
6512
+ responses:
6513
+ "200":
6514
+ description: Card voided
6515
+ content:
6516
+ application/json:
6517
+ schema:
6518
+ $ref: "#/components/schemas/CardResponse"
6519
+ "404":
6520
+ $ref: "#/components/responses/NotFound"
6521
+
6522
+ /v1/cards/{card_id}/refresh:
6523
+ post:
6524
+ tags: [Payment Cards]
6525
+ summary: Refresh a card's balance
6526
+ description: Proxy Laso refresh to update balance/status. Rate-limited to once per 5 minutes per card (429 on exceed).
6527
+ operationId: refreshCard
6528
+ parameters:
6529
+ - $ref: "#/components/parameters/CardId"
6530
+ responses:
6531
+ "200":
6532
+ description: Card refreshed
6533
+ content:
6534
+ application/json:
6535
+ schema:
6536
+ $ref: "#/components/schemas/CardResponse"
6537
+ "429":
6538
+ description: Refreshed too recently
6539
+ "404":
6540
+ $ref: "#/components/responses/NotFound"
6541
+
6334
6542
  # =============================================================================
6335
6543
  # COMPONENTS
6336
6544
  # =============================================================================
@@ -6375,6 +6583,13 @@ components:
6375
6583
  schema:
6376
6584
  type: string
6377
6585
  format: uuid
6586
+ CardId:
6587
+ name: card_id
6588
+ in: path
6589
+ required: true
6590
+ schema:
6591
+ type: string
6592
+ format: uuid
6378
6593
  IncludeSignedTx:
6379
6594
  name: include_signed_tx
6380
6595
  in: query
@@ -6427,6 +6642,149 @@ components:
6427
6642
  $ref: "#/components/schemas/ProblemDetails"
6428
6643
 
6429
6644
  schemas:
6645
+ OrderCardRequest:
6646
+ type: object
6647
+ required: [kind, amount_usd]
6648
+ properties:
6649
+ kind:
6650
+ type: string
6651
+ enum: [prepaid, gift_card]
6652
+ amount_usd:
6653
+ type: string
6654
+ description: USD amount to load onto the card.
6655
+ example: "25.00"
6656
+ laso_server_id:
6657
+ type: string
6658
+ description: Optional Laso gift-card server/brand id (gift cards only).
6659
+ country:
6660
+ type: string
6661
+ description: Optional country (prepaid cards; defaults to US).
6662
+ CardResponse:
6663
+ type: object
6664
+ description: Masked card view — never contains PAN/CVV.
6665
+ required: [id, issuer, kind, currency, status, storage_mode, reveal_policy, created_at, updated_at]
6666
+ properties:
6667
+ id:
6668
+ type: string
6669
+ format: uuid
6670
+ agent_id:
6671
+ type: string
6672
+ format: uuid
6673
+ nullable: true
6674
+ issuer:
6675
+ type: string
6676
+ enum: [laso, manual]
6677
+ kind:
6678
+ type: string
6679
+ enum: [prepaid, gift_card]
6680
+ brand:
6681
+ type: string
6682
+ last4:
6683
+ type: string
6684
+ exp_month:
6685
+ type: integer
6686
+ exp_year:
6687
+ type: integer
6688
+ currency:
6689
+ type: string
6690
+ order_amount_usd:
6691
+ type: string
6692
+ balance:
6693
+ type: string
6694
+ status:
6695
+ type: string
6696
+ enum: [ordering, pending, ready, depleted, expired, voided, orphaned_payment]
6697
+ storage_mode:
6698
+ type: string
6699
+ enum: [reference, full]
6700
+ reveal_policy:
6701
+ type: object
6702
+ additionalProperties: true
6703
+ void_after:
6704
+ type: string
6705
+ format: date-time
6706
+ created_at:
6707
+ type: string
6708
+ format: date-time
6709
+ updated_at:
6710
+ type: string
6711
+ format: date-time
6712
+ CardListResponse:
6713
+ type: object
6714
+ required: [cards]
6715
+ properties:
6716
+ cards:
6717
+ type: array
6718
+ items:
6719
+ $ref: "#/components/schemas/CardResponse"
6720
+ CardRevealResponse:
6721
+ type: object
6722
+ description: Revealed card details — sensitive. Returned only by the reveal endpoint.
6723
+ required: [id, disclaimer]
6724
+ properties:
6725
+ id:
6726
+ type: string
6727
+ format: uuid
6728
+ pan:
6729
+ type: string
6730
+ cvv:
6731
+ type: string
6732
+ exp_month:
6733
+ type: integer
6734
+ exp_year:
6735
+ type: integer
6736
+ brand:
6737
+ type: string
6738
+ redemption:
6739
+ type: object
6740
+ additionalProperties: true
6741
+ description: Gift-card redemption payload (URL/code/PIN) when applicable.
6742
+ disclaimer:
6743
+ type: string
6744
+ UpdateCardRequest:
6745
+ type: object
6746
+ description: Human-settable per-card reveal policy + lifecycle controls.
6747
+ properties:
6748
+ agent_reveal:
6749
+ type: boolean
6750
+ max_reveals:
6751
+ type: integer
6752
+ reveal_expires_at:
6753
+ type: string
6754
+ format: date-time
6755
+ nullable: true
6756
+ void_after:
6757
+ type: string
6758
+ format: date-time
6759
+ nullable: true
6760
+ ImportCardRequest:
6761
+ type: object
6762
+ required: [pan, cvv, exp_month, exp_year]
6763
+ properties:
6764
+ pan:
6765
+ type: string
6766
+ cvv:
6767
+ type: string
6768
+ exp_month:
6769
+ type: integer
6770
+ exp_year:
6771
+ type: integer
6772
+ brand:
6773
+ type: string
6774
+ currency:
6775
+ type: string
6776
+ balance:
6777
+ type: string
6778
+ agent_id:
6779
+ type: string
6780
+ format: uuid
6781
+ SearchGiftCardsRequest:
6782
+ type: object
6783
+ properties:
6784
+ query:
6785
+ type: string
6786
+ country:
6787
+ type: string
6430
6788
  ProblemDetails:
6431
6789
  type: object
6432
6790
  description: RFC 7807 error envelope
@@ -7376,6 +7734,23 @@ components:
7376
7734
  items:
7377
7735
  type: string
7378
7736
  description: Solana wallet addresses whose ATAs may be created. Empty = unrestricted.
7737
+ cards_enabled:
7738
+ type: boolean
7739
+ description: Whether this agent may order payment cards (x402 card ordering). Pro+ tier.
7740
+ card_max_order_usd:
7741
+ type: string
7742
+ description: Maximum USD amount for a single card order.
7743
+ card_daily_limit_usd:
7744
+ type: string
7745
+ description: Maximum cumulative USD spent ordering cards per rolling 24h window.
7746
+ card_payto_allowlist:
7747
+ type: array
7748
+ items:
7749
+ type: string
7750
+ description: Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients).
7751
+ card_reveal_enabled:
7752
+ type: boolean
7753
+ description: Whether agents may reveal card details subject to per-card reveal policy.
7379
7754
  api_key_expires_at:
7380
7755
  type: string
7381
7756
  format: date-time
@@ -7461,6 +7836,25 @@ components:
7461
7836
  items:
7462
7837
  type: string
7463
7838
  description: Solana wallet addresses whose ATAs may be created.
7839
+ cards_enabled:
7840
+ type: boolean
7841
+ description: Whether this agent may order payment cards (x402 card ordering). Pro+ tier.
7842
+ card_max_order_usd:
7843
+ type: string
7844
+ nullable: true
7845
+ description: Maximum USD amount for a single card order. null clears.
7846
+ card_daily_limit_usd:
7847
+ type: string
7848
+ nullable: true
7849
+ description: Maximum cumulative USD spent ordering cards per rolling 24h window. null clears.
7850
+ card_payto_allowlist:
7851
+ type: array
7852
+ items:
7853
+ type: string
7854
+ description: Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients).
7855
+ card_reveal_enabled:
7856
+ type: boolean
7857
+ description: Whether agents may reveal card details subject to per-card reveal policy.
7464
7858
  federation_enabled:
7465
7859
  type: boolean
7466
7860
  description: |
@@ -7628,6 +8022,23 @@ components:
7628
8022
  items:
7629
8023
  type: string
7630
8024
  description: Solana wallet addresses whose ATAs may be created.
8025
+ cards_enabled:
8026
+ type: boolean
8027
+ description: Whether this agent may order payment cards (x402 card ordering).
8028
+ card_max_order_usd:
8029
+ type: string
8030
+ description: Maximum USD amount for a single card order.
8031
+ card_daily_limit_usd:
8032
+ type: string
8033
+ description: Maximum cumulative USD spent ordering cards per rolling 24h window.
8034
+ card_payto_allowlist:
8035
+ type: array
8036
+ items:
8037
+ type: string
8038
+ description: Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients).
8039
+ card_reveal_enabled:
8040
+ type: boolean
8041
+ description: Whether agents may reveal card details subject to per-card reveal policy.
7631
8042
  tx_count_today:
7632
8043
  type: integer
7633
8044
  description: Today's transaction count (UTC calendar day). Present when intents_api_enabled.
package/package.json CHANGED
@@ -1,40 +1,40 @@
1
1
  {
2
- "name": "@1claw/openapi-spec",
3
- "version": "0.41.2",
4
- "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API — generate clients in any language",
5
- "license": "MIT",
6
- "repository": {
7
- "type": "git",
8
- "url": "https://github.com/1clawAI/1claw.git",
9
- "directory": "packages/openapi-spec"
10
- },
11
- "files": [
12
- "openapi.yaml",
13
- "openapi.json",
14
- "README.md"
15
- ],
16
- "exports": {
17
- "./openapi.yaml": "./openapi.yaml",
18
- "./openapi.json": "./openapi.json"
19
- },
20
- "scripts": {
21
- "build": "node scripts/yaml-to-json.mjs",
22
- "prepublishOnly": "npm run build"
23
- },
24
- "publishConfig": {
25
- "access": "public"
26
- },
27
- "keywords": [
28
- "1claw",
29
- "openapi",
30
- "api-spec",
31
- "codegen",
32
- "swagger",
33
- "secrets",
34
- "vault",
35
- "ai-agents"
36
- ],
37
- "devDependencies": {
38
- "js-yaml": "^4.1.1"
39
- }
2
+ "name": "@1claw/openapi-spec",
3
+ "version": "0.41.3",
4
+ "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API \u2014 generate clients in any language",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "https://github.com/1clawAI/1claw.git",
9
+ "directory": "packages/openapi-spec"
10
+ },
11
+ "files": [
12
+ "openapi.yaml",
13
+ "openapi.json",
14
+ "README.md"
15
+ ],
16
+ "exports": {
17
+ "./openapi.yaml": "./openapi.yaml",
18
+ "./openapi.json": "./openapi.json"
19
+ },
20
+ "scripts": {
21
+ "build": "node scripts/yaml-to-json.mjs",
22
+ "prepublishOnly": "npm run build"
23
+ },
24
+ "publishConfig": {
25
+ "access": "public"
26
+ },
27
+ "keywords": [
28
+ "1claw",
29
+ "openapi",
30
+ "api-spec",
31
+ "codegen",
32
+ "swagger",
33
+ "secrets",
34
+ "vault",
35
+ "ai-agents"
36
+ ],
37
+ "devDependencies": {
38
+ "js-yaml": "^4.1.1"
39
+ }
40
40
  }