@1claw/openapi-spec 0.37.0 → 0.39.0

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 (4) hide show
  1. package/README.md +1 -1
  2. package/openapi.json +395 -8
  3. package/openapi.yaml +263 -2
  4. package/package.json +2 -2
package/README.md CHANGED
@@ -87,7 +87,7 @@ import spec from "@1claw/openapi-spec/openapi.json";
87
87
  - **Smart Accounts** — Per-agent multi-chain Safe accounts: `POST /v1/agents/{id}/smart-accounts`, `GET /v1/agents/{id}` returns `smart_accounts[]`. One EOA signer per agent, Intents API resolves Safe by `chain_id`.
88
88
  - **Vaults** — CRUD, CMEK enable/disable, key rotation with job tracking, MPC enable/disable (`POST /v1/vaults/{id}/mpc`, `DELETE /v1/vaults/{id}/mpc`)
89
89
  - **Secrets** — CRUD, versioning, CMEK-encrypted flag, `client_share` in responses (MPC vaults)
90
- - **Agents** — CRUD with `auth_method` (api_key, mtls, oidc_client_credentials), auto-generated SSH keypairs, `token_ttl_seconds`, `vault_ids`, Intents API, transaction guardrails (`tx_to_allowlist`, `tx_max_value_eth`, `tx_daily_limit_eth`, `tx_allowed_chains`), **OIDC federation knobs** (`federation_enabled`, `federation_audiences`, `federated_token_ttl_seconds`); **`GET /v1/agents/{id}`** includes **`tx_spent_today_eth`** (rolling UTC-day spend from recorded txs) for clients such as **Shroud** that enforce the daily cap alongside per-tx limits
90
+ - **Agents** — CRUD with `auth_method` (api_key, mtls, oidc_client_credentials), auto-generated SSH keypairs, `token_ttl_seconds`, `vault_ids`, Intents API, transaction guardrails (`tx_to_allowlist`, `tx_max_value` (native major units), `tx_daily_limit` (per-chain), `tx_allowed_chains`), **OIDC federation knobs** (`federation_enabled`, `federation_audiences`, `federated_token_ttl_seconds`); **`GET /v1/agents/{id}`** includes **`tx_spent_today`** and **`tx_spent_today_by_chain`** (per-chain daily spend in native units) for clients such as **Shroud** that enforce the daily cap alongside per-tx limits. Deprecated aliases `tx_max_value_eth`, `tx_daily_limit_eth`, `tx_spent_today_eth` are still accepted/returned for backward compatibility.
91
91
  - **Signing Keys** — Multi-chain key management: `POST /v1/agents/{id}/signing-keys` (provision), `GET .../signing-keys` (list), `POST .../signing-keys/{chain}/rotate`, `DELETE .../signing-keys/{chain}` (deactivate). Supports ethereum, bitcoin, solana, xrp, cardano, tron
92
92
  - **Unified Signing** — `POST /v1/agents/{id}/sign` — single endpoint for EIP-191 personal_sign, EIP-712 typed_data, and EIP-2718 transaction types (legacy, EIP-1559, EIP-4844, EIP-7702)
93
93
  - **Policies** — Glob-based access control
package/openapi.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "openapi": "3.1.0",
3
3
  "info": {
4
4
  "title": "1Claw API",
5
- "version": "2.24.0",
5
+ "version": "2.25.0",
6
6
  "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",
7
7
  "contact": {
8
8
  "email": "ops@1claw.xyz"
@@ -122,6 +122,10 @@
122
122
  {
123
123
  "name": "Risk Engine",
124
124
  "description": "Risk events, verdicts, and honeytoken management"
125
+ },
126
+ {
127
+ "name": "Tokens",
128
+ "description": "Known token registry for guardrail enforcement"
125
129
  }
126
130
  ],
127
131
  "paths": {
@@ -9385,6 +9389,142 @@
9385
9389
  }
9386
9390
  }
9387
9391
  }
9392
+ },
9393
+ "/v1/tokens": {
9394
+ "get": {
9395
+ "tags": [
9396
+ "Tokens"
9397
+ ],
9398
+ "summary": "List known tokens",
9399
+ "operationId": "listKnownTokens",
9400
+ "parameters": [
9401
+ {
9402
+ "name": "chain",
9403
+ "in": "query",
9404
+ "schema": {
9405
+ "type": "string"
9406
+ },
9407
+ "description": "Filter by chain name"
9408
+ }
9409
+ ],
9410
+ "responses": {
9411
+ "200": {
9412
+ "description": "Token list",
9413
+ "content": {
9414
+ "application/json": {
9415
+ "schema": {
9416
+ "$ref": "#/components/schemas/KnownTokenListResponse"
9417
+ }
9418
+ }
9419
+ }
9420
+ }
9421
+ }
9422
+ }
9423
+ },
9424
+ "/v1/chains/{chain_name}/tokens": {
9425
+ "get": {
9426
+ "tags": [
9427
+ "Tokens"
9428
+ ],
9429
+ "summary": "List tokens for a specific chain",
9430
+ "operationId": "listTokensByChain",
9431
+ "parameters": [
9432
+ {
9433
+ "name": "chain_name",
9434
+ "in": "path",
9435
+ "required": true,
9436
+ "schema": {
9437
+ "type": "string"
9438
+ }
9439
+ }
9440
+ ],
9441
+ "responses": {
9442
+ "200": {
9443
+ "description": "Token list for chain",
9444
+ "content": {
9445
+ "application/json": {
9446
+ "schema": {
9447
+ "$ref": "#/components/schemas/KnownTokenListResponse"
9448
+ }
9449
+ }
9450
+ }
9451
+ }
9452
+ }
9453
+ }
9454
+ },
9455
+ "/v1/admin/tokens": {
9456
+ "post": {
9457
+ "tags": [
9458
+ "Admin",
9459
+ "Tokens"
9460
+ ],
9461
+ "summary": "Create a known token (admin only)",
9462
+ "operationId": "createKnownToken",
9463
+ "security": [
9464
+ {
9465
+ "BearerAuth": []
9466
+ }
9467
+ ],
9468
+ "requestBody": {
9469
+ "required": true,
9470
+ "content": {
9471
+ "application/json": {
9472
+ "schema": {
9473
+ "$ref": "#/components/schemas/CreateKnownTokenRequest"
9474
+ }
9475
+ }
9476
+ }
9477
+ },
9478
+ "responses": {
9479
+ "201": {
9480
+ "description": "Token created",
9481
+ "content": {
9482
+ "application/json": {
9483
+ "schema": {
9484
+ "$ref": "#/components/schemas/KnownToken"
9485
+ }
9486
+ }
9487
+ }
9488
+ },
9489
+ "403": {
9490
+ "$ref": "#/components/responses/Forbidden"
9491
+ }
9492
+ }
9493
+ }
9494
+ },
9495
+ "/v1/admin/tokens/{token_id}": {
9496
+ "delete": {
9497
+ "tags": [
9498
+ "Admin",
9499
+ "Tokens"
9500
+ ],
9501
+ "summary": "Delete a known token (admin only)",
9502
+ "operationId": "deleteKnownToken",
9503
+ "security": [
9504
+ {
9505
+ "BearerAuth": []
9506
+ }
9507
+ ],
9508
+ "parameters": [
9509
+ {
9510
+ "name": "token_id",
9511
+ "in": "path",
9512
+ "required": true,
9513
+ "schema": {
9514
+ "type": "string",
9515
+ "format": "uuid"
9516
+ }
9517
+ }
9518
+ ],
9519
+ "responses": {
9520
+ "204": {
9521
+ "description": "Token deleted"
9522
+ },
9523
+ "403": {
9524
+ "$ref": "#/components/responses/Forbidden"
9525
+ }
9526
+ }
9527
+ }
9388
9528
  }
9389
9529
  },
9390
9530
  "components": {
@@ -10734,11 +10874,23 @@
10734
10874
  "type": "string"
10735
10875
  }
10736
10876
  },
10877
+ "tx_max_value": {
10878
+ "type": "string",
10879
+ "description": "Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX)."
10880
+ },
10881
+ "tx_daily_limit": {
10882
+ "type": "string",
10883
+ "description": "Rolling daily spend cap in native major units, enforced per chain family at signing time."
10884
+ },
10737
10885
  "tx_max_value_eth": {
10738
- "type": "string"
10886
+ "type": "string",
10887
+ "deprecated": true,
10888
+ "description": "Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only)."
10739
10889
  },
10740
10890
  "tx_daily_limit_eth": {
10741
- "type": "string"
10891
+ "type": "string",
10892
+ "deprecated": true,
10893
+ "description": "Deprecated alias for tx_daily_limit."
10742
10894
  },
10743
10895
  "tx_allowed_chains": {
10744
10896
  "type": "array",
@@ -10779,6 +10931,30 @@
10779
10931
  "shroud_config": {
10780
10932
  "$ref": "#/components/schemas/ShroudConfig"
10781
10933
  },
10934
+ "tx_token_allowlist": {
10935
+ "type": "array",
10936
+ "items": {
10937
+ "type": "string"
10938
+ },
10939
+ "description": "Token contract/mint addresses this agent may interact with. Empty = unrestricted."
10940
+ },
10941
+ "tx_known_tokens_only": {
10942
+ "type": "boolean",
10943
+ "default": false,
10944
+ "description": "When true, only tokens in the known_tokens registry may be used."
10945
+ },
10946
+ "xrpl_allowed_tx_types": {
10947
+ "type": "array",
10948
+ "items": {
10949
+ "type": "string"
10950
+ },
10951
+ "description": "Allowed XRP Ledger transaction types (Payment, TrustSet, etc.). Empty = all allowed."
10952
+ },
10953
+ "per_chain_guardrails": {
10954
+ "type": "object",
10955
+ "additionalProperties": true,
10956
+ "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"
10957
+ },
10782
10958
  "api_key_expires_at": {
10783
10959
  "type": "string",
10784
10960
  "format": "date-time",
@@ -10815,11 +10991,23 @@
10815
10991
  "type": "string"
10816
10992
  }
10817
10993
  },
10994
+ "tx_max_value": {
10995
+ "type": "string",
10996
+ "description": "Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX)."
10997
+ },
10998
+ "tx_daily_limit": {
10999
+ "type": "string",
11000
+ "description": "Rolling daily spend cap in native major units, enforced per chain family at signing time."
11001
+ },
10818
11002
  "tx_max_value_eth": {
10819
- "type": "string"
11003
+ "type": "string",
11004
+ "deprecated": true,
11005
+ "description": "Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only)."
10820
11006
  },
10821
11007
  "tx_daily_limit_eth": {
10822
- "type": "string"
11008
+ "type": "string",
11009
+ "deprecated": true,
11010
+ "description": "Deprecated alias for tx_daily_limit."
10823
11011
  },
10824
11012
  "tx_allowed_chains": {
10825
11013
  "type": "array",
@@ -10864,6 +11052,30 @@
10864
11052
  "nullable": true,
10865
11053
  "description": "Per-agent TTL override for federation tokens (seconds). NULL falls\nback to the global default (`ONECLAW_JWT_FEDERATED_TOKEN_EXPIRY_SECS`).\nHard-capped at 3600 seconds.\n"
10866
11054
  },
11055
+ "tx_token_allowlist": {
11056
+ "type": "array",
11057
+ "items": {
11058
+ "type": "string"
11059
+ },
11060
+ "description": "Token contract/mint addresses this agent may interact with. Empty = unrestricted."
11061
+ },
11062
+ "tx_known_tokens_only": {
11063
+ "type": "boolean",
11064
+ "default": false,
11065
+ "description": "When true, only tokens in the known_tokens registry may be used."
11066
+ },
11067
+ "xrpl_allowed_tx_types": {
11068
+ "type": "array",
11069
+ "items": {
11070
+ "type": "string"
11071
+ },
11072
+ "description": "Allowed XRP Ledger transaction types (Payment, TrustSet, etc.). Empty = all allowed."
11073
+ },
11074
+ "per_chain_guardrails": {
11075
+ "type": "object",
11076
+ "additionalProperties": true,
11077
+ "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"
11078
+ },
10867
11079
  "api_key_expires_at": {
10868
11080
  "type": "string",
10869
11081
  "format": "date-time",
@@ -10920,15 +11132,32 @@
10920
11132
  "type": "string"
10921
11133
  }
10922
11134
  },
11135
+ "tx_max_value": {
11136
+ "type": "string",
11137
+ "description": "Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX)."
11138
+ },
11139
+ "tx_daily_limit": {
11140
+ "type": "string",
11141
+ "description": "Rolling daily spend cap in native major units, enforced per chain family at signing time."
11142
+ },
10923
11143
  "tx_max_value_eth": {
10924
- "type": "string"
11144
+ "type": "string",
11145
+ "deprecated": true,
11146
+ "description": "Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only)."
10925
11147
  },
10926
11148
  "tx_daily_limit_eth": {
10927
- "type": "string"
11149
+ "type": "string",
11150
+ "deprecated": true,
11151
+ "description": "Deprecated alias for tx_daily_limit."
11152
+ },
11153
+ "tx_spent_today": {
11154
+ "type": "string",
11155
+ "description": "Sum of today's spend across all chain families in major units. Prefer tx_spent_today_by_chain."
10928
11156
  },
10929
11157
  "tx_spent_today_eth": {
10930
11158
  "type": "string",
10931
- "description": "ETH value already spent today (UTC) from recorded transactions; used with daily limit guardrails"
11159
+ "deprecated": true,
11160
+ "description": "Deprecated alias for tx_spent_today."
10932
11161
  },
10933
11162
  "tx_allowed_chains": {
10934
11163
  "type": "array",
@@ -11021,6 +11250,36 @@
11021
11250
  "type": "boolean",
11022
11251
  "description": "Whether the raw/precomputed-digest signing intent (eip712_digest) is enabled. Blind signing — bypasses transaction guardrails; OFF by default and human-set. Required for ERC-1271/ERC-7739 flows (e.g. Polymarket).\n"
11023
11252
  },
11253
+ "tx_token_allowlist": {
11254
+ "type": "array",
11255
+ "items": {
11256
+ "type": "string"
11257
+ },
11258
+ "description": "Token contract/mint addresses this agent may interact with."
11259
+ },
11260
+ "tx_known_tokens_only": {
11261
+ "type": "boolean",
11262
+ "description": "When true, only tokens in the known_tokens registry may be used."
11263
+ },
11264
+ "xrpl_allowed_tx_types": {
11265
+ "type": "array",
11266
+ "items": {
11267
+ "type": "string"
11268
+ },
11269
+ "description": "Allowed XRP Ledger transaction types."
11270
+ },
11271
+ "per_chain_guardrails": {
11272
+ "type": "object",
11273
+ "additionalProperties": true,
11274
+ "description": "Per-chain guardrail overrides."
11275
+ },
11276
+ "tx_spent_today_by_chain": {
11277
+ "type": "object",
11278
+ "additionalProperties": {
11279
+ "type": "string"
11280
+ },
11281
+ "description": "Per-chain-family daily spend in native major units (keys: evm, bitcoin, solana, xrp, cardano, tron)."
11282
+ },
11024
11283
  "api_key_expires_at": {
11025
11284
  "type": "string",
11026
11285
  "format": "date-time",
@@ -11053,6 +11312,111 @@
11053
11312
  }
11054
11313
  }
11055
11314
  },
11315
+ "KnownToken": {
11316
+ "type": "object",
11317
+ "required": [
11318
+ "id",
11319
+ "chain",
11320
+ "symbol",
11321
+ "name",
11322
+ "contract_address",
11323
+ "decimals",
11324
+ "is_testnet",
11325
+ "is_verified"
11326
+ ],
11327
+ "properties": {
11328
+ "id": {
11329
+ "type": "string",
11330
+ "format": "uuid"
11331
+ },
11332
+ "chain": {
11333
+ "type": "string"
11334
+ },
11335
+ "symbol": {
11336
+ "type": "string"
11337
+ },
11338
+ "name": {
11339
+ "type": "string"
11340
+ },
11341
+ "contract_address": {
11342
+ "type": "string"
11343
+ },
11344
+ "decimals": {
11345
+ "type": "integer"
11346
+ },
11347
+ "is_testnet": {
11348
+ "type": "boolean"
11349
+ },
11350
+ "is_verified": {
11351
+ "type": "boolean"
11352
+ },
11353
+ "logo_url": {
11354
+ "type": "string",
11355
+ "nullable": true
11356
+ },
11357
+ "created_at": {
11358
+ "type": "string",
11359
+ "format": "date-time"
11360
+ },
11361
+ "updated_at": {
11362
+ "type": "string",
11363
+ "format": "date-time"
11364
+ }
11365
+ }
11366
+ },
11367
+ "KnownTokenListResponse": {
11368
+ "type": "object",
11369
+ "required": [
11370
+ "tokens"
11371
+ ],
11372
+ "properties": {
11373
+ "tokens": {
11374
+ "type": "array",
11375
+ "items": {
11376
+ "$ref": "#/components/schemas/KnownToken"
11377
+ }
11378
+ }
11379
+ }
11380
+ },
11381
+ "CreateKnownTokenRequest": {
11382
+ "type": "object",
11383
+ "required": [
11384
+ "chain",
11385
+ "symbol",
11386
+ "name",
11387
+ "contract_address",
11388
+ "decimals"
11389
+ ],
11390
+ "properties": {
11391
+ "chain": {
11392
+ "type": "string"
11393
+ },
11394
+ "symbol": {
11395
+ "type": "string"
11396
+ },
11397
+ "name": {
11398
+ "type": "string"
11399
+ },
11400
+ "contract_address": {
11401
+ "type": "string"
11402
+ },
11403
+ "decimals": {
11404
+ "type": "integer"
11405
+ },
11406
+ "is_testnet": {
11407
+ "type": "boolean",
11408
+ "default": false
11409
+ },
11410
+ "is_verified": {
11411
+ "type": "boolean",
11412
+ "default": true
11413
+ },
11414
+ "logo_url": {
11415
+ "type": "string",
11416
+ "nullable": true
11417
+ }
11418
+ }
11419
+ },
11056
11420
  "AgentSmartAccountResponse": {
11057
11421
  "type": "object",
11058
11422
  "description": "One Safe smart account per chain for an agent",
@@ -14367,6 +14731,29 @@
14367
14731
  },
14368
14732
  "balance_display": {
14369
14733
  "type": "string"
14734
+ },
14735
+ "tokens": {
14736
+ "type": "array",
14737
+ "description": "Token balances when ?tokens= query param is provided",
14738
+ "items": {
14739
+ "type": "object",
14740
+ "properties": {
14741
+ "contract_address": {
14742
+ "type": "string"
14743
+ },
14744
+ "symbol": {
14745
+ "type": "string",
14746
+ "nullable": true
14747
+ },
14748
+ "balance": {
14749
+ "type": "string"
14750
+ },
14751
+ "decimals": {
14752
+ "type": "integer",
14753
+ "nullable": true
14754
+ }
14755
+ }
14756
+ }
14370
14757
  }
14371
14758
  }
14372
14759
  },
package/openapi.yaml CHANGED
@@ -2,7 +2,7 @@ openapi: 3.1.0
2
2
 
3
3
  info:
4
4
  title: 1Claw API
5
- version: 2.24.0
5
+ version: 2.25.0
6
6
  description: |
7
7
  Secure secret management for AI agents. Provides vaults, secrets,
8
8
  policy-based access control, agent identity, Intents API,
@@ -74,6 +74,8 @@ tags:
74
74
  description: OAuth 2.0 authorization server (PKCE, consent, token exchange, OIDC UserInfo)
75
75
  - name: Risk Engine
76
76
  description: Risk events, verdicts, and honeytoken management
77
+ - name: Tokens
78
+ description: Known token registry for guardrail enforcement
77
79
 
78
80
  # =============================================================================
79
81
  # PATHS
@@ -5986,6 +5988,87 @@ paths:
5986
5988
  "404":
5987
5989
  $ref: "#/components/responses/NotFound"
5988
5990
 
5991
+ /v1/tokens:
5992
+ get:
5993
+ tags: [Tokens]
5994
+ summary: List known tokens
5995
+ operationId: listKnownTokens
5996
+ parameters:
5997
+ - name: chain
5998
+ in: query
5999
+ schema:
6000
+ type: string
6001
+ description: Filter by chain name
6002
+ responses:
6003
+ "200":
6004
+ description: Token list
6005
+ content:
6006
+ application/json:
6007
+ schema:
6008
+ $ref: "#/components/schemas/KnownTokenListResponse"
6009
+
6010
+ /v1/chains/{chain_name}/tokens:
6011
+ get:
6012
+ tags: [Tokens]
6013
+ summary: List tokens for a specific chain
6014
+ operationId: listTokensByChain
6015
+ parameters:
6016
+ - name: chain_name
6017
+ in: path
6018
+ required: true
6019
+ schema:
6020
+ type: string
6021
+ responses:
6022
+ "200":
6023
+ description: Token list for chain
6024
+ content:
6025
+ application/json:
6026
+ schema:
6027
+ $ref: "#/components/schemas/KnownTokenListResponse"
6028
+
6029
+ /v1/admin/tokens:
6030
+ post:
6031
+ tags: [Admin, Tokens]
6032
+ summary: Create a known token (admin only)
6033
+ operationId: createKnownToken
6034
+ security:
6035
+ - BearerAuth: []
6036
+ requestBody:
6037
+ required: true
6038
+ content:
6039
+ application/json:
6040
+ schema:
6041
+ $ref: "#/components/schemas/CreateKnownTokenRequest"
6042
+ responses:
6043
+ "201":
6044
+ description: Token created
6045
+ content:
6046
+ application/json:
6047
+ schema:
6048
+ $ref: "#/components/schemas/KnownToken"
6049
+ "403":
6050
+ $ref: "#/components/responses/Forbidden"
6051
+
6052
+ /v1/admin/tokens/{token_id}:
6053
+ delete:
6054
+ tags: [Admin, Tokens]
6055
+ summary: Delete a known token (admin only)
6056
+ operationId: deleteKnownToken
6057
+ security:
6058
+ - BearerAuth: []
6059
+ parameters:
6060
+ - name: token_id
6061
+ in: path
6062
+ required: true
6063
+ schema:
6064
+ type: string
6065
+ format: uuid
6066
+ responses:
6067
+ "204":
6068
+ description: Token deleted
6069
+ "403":
6070
+ $ref: "#/components/responses/Forbidden"
6071
+
5989
6072
  # =============================================================================
5990
6073
  # COMPONENTS
5991
6074
  # =============================================================================
@@ -6936,10 +7019,20 @@ components:
6936
7019
  type: array
6937
7020
  items:
6938
7021
  type: string
7022
+ tx_max_value:
7023
+ type: string
7024
+ description: Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX).
7025
+ tx_daily_limit:
7026
+ type: string
7027
+ description: Rolling daily spend cap in native major units, enforced per chain family at signing time.
6939
7028
  tx_max_value_eth:
6940
7029
  type: string
7030
+ deprecated: true
7031
+ description: Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only).
6941
7032
  tx_daily_limit_eth:
6942
7033
  type: string
7034
+ deprecated: true
7035
+ description: Deprecated alias for tx_daily_limit.
6943
7036
  tx_allowed_chains:
6944
7037
  type: array
6945
7038
  items:
@@ -6969,6 +7062,27 @@ components:
6969
7062
  description: Enable Shroud LLM Proxy for this agent
6970
7063
  shroud_config:
6971
7064
  $ref: "#/components/schemas/ShroudConfig"
7065
+ tx_token_allowlist:
7066
+ type: array
7067
+ items:
7068
+ type: string
7069
+ description: Token contract/mint addresses this agent may interact with. Empty = unrestricted.
7070
+ tx_known_tokens_only:
7071
+ type: boolean
7072
+ default: false
7073
+ description: When true, only tokens in the known_tokens registry may be used.
7074
+ xrpl_allowed_tx_types:
7075
+ type: array
7076
+ items:
7077
+ type: string
7078
+ description: Allowed XRP Ledger transaction types (Payment, TrustSet, etc.). Empty = all allowed.
7079
+ per_chain_guardrails:
7080
+ type: object
7081
+ additionalProperties: true
7082
+ description: |
7083
+ Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron).
7084
+ Each value may include max_value, daily_limit, to_allowlist, token_allowlist (legacy *_eth keys accepted).
7085
+ Strictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.
6972
7086
  api_key_expires_at:
6973
7087
  type: string
6974
7088
  format: date-time
@@ -6995,10 +7109,20 @@ components:
6995
7109
  type: array
6996
7110
  items:
6997
7111
  type: string
7112
+ tx_max_value:
7113
+ type: string
7114
+ description: Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX).
7115
+ tx_daily_limit:
7116
+ type: string
7117
+ description: Rolling daily spend cap in native major units, enforced per chain family at signing time.
6998
7118
  tx_max_value_eth:
6999
7119
  type: string
7120
+ deprecated: true
7121
+ description: Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only).
7000
7122
  tx_daily_limit_eth:
7001
7123
  type: string
7124
+ deprecated: true
7125
+ description: Deprecated alias for tx_daily_limit.
7002
7126
  tx_allowed_chains:
7003
7127
  type: array
7004
7128
  items:
@@ -7040,6 +7164,27 @@ components:
7040
7164
  Per-agent TTL override for federation tokens (seconds). NULL falls
7041
7165
  back to the global default (`ONECLAW_JWT_FEDERATED_TOKEN_EXPIRY_SECS`).
7042
7166
  Hard-capped at 3600 seconds.
7167
+ tx_token_allowlist:
7168
+ type: array
7169
+ items:
7170
+ type: string
7171
+ description: Token contract/mint addresses this agent may interact with. Empty = unrestricted.
7172
+ tx_known_tokens_only:
7173
+ type: boolean
7174
+ default: false
7175
+ description: When true, only tokens in the known_tokens registry may be used.
7176
+ xrpl_allowed_tx_types:
7177
+ type: array
7178
+ items:
7179
+ type: string
7180
+ description: Allowed XRP Ledger transaction types (Payment, TrustSet, etc.). Empty = all allowed.
7181
+ per_chain_guardrails:
7182
+ type: object
7183
+ additionalProperties: true
7184
+ description: |
7185
+ Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron).
7186
+ Each value may include max_value, daily_limit, to_allowlist, token_allowlist (legacy *_eth keys accepted).
7187
+ Strictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.
7043
7188
  api_key_expires_at:
7044
7189
  type: string
7045
7190
  format: date-time
@@ -7081,13 +7226,27 @@ components:
7081
7226
  type: array
7082
7227
  items:
7083
7228
  type: string
7229
+ tx_max_value:
7230
+ type: string
7231
+ description: Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX).
7232
+ tx_daily_limit:
7233
+ type: string
7234
+ description: Rolling daily spend cap in native major units, enforced per chain family at signing time.
7084
7235
  tx_max_value_eth:
7085
7236
  type: string
7237
+ deprecated: true
7238
+ description: Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only).
7086
7239
  tx_daily_limit_eth:
7087
7240
  type: string
7241
+ deprecated: true
7242
+ description: Deprecated alias for tx_daily_limit.
7243
+ tx_spent_today:
7244
+ type: string
7245
+ description: Sum of today's spend across all chain families in major units. Prefer tx_spent_today_by_chain.
7088
7246
  tx_spent_today_eth:
7089
7247
  type: string
7090
- description: ETH value already spent today (UTC) from recorded transactions; used with daily limit guardrails
7248
+ deprecated: true
7249
+ description: Deprecated alias for tx_spent_today.
7091
7250
  tx_allowed_chains:
7092
7251
  type: array
7093
7252
  items:
@@ -7158,6 +7317,28 @@ components:
7158
7317
  Whether the raw/precomputed-digest signing intent (eip712_digest) is
7159
7318
  enabled. Blind signing — bypasses transaction guardrails; OFF by default
7160
7319
  and human-set. Required for ERC-1271/ERC-7739 flows (e.g. Polymarket).
7320
+ tx_token_allowlist:
7321
+ type: array
7322
+ items:
7323
+ type: string
7324
+ description: Token contract/mint addresses this agent may interact with.
7325
+ tx_known_tokens_only:
7326
+ type: boolean
7327
+ description: When true, only tokens in the known_tokens registry may be used.
7328
+ xrpl_allowed_tx_types:
7329
+ type: array
7330
+ items:
7331
+ type: string
7332
+ description: Allowed XRP Ledger transaction types.
7333
+ per_chain_guardrails:
7334
+ type: object
7335
+ additionalProperties: true
7336
+ description: Per-chain guardrail overrides.
7337
+ tx_spent_today_by_chain:
7338
+ type: object
7339
+ additionalProperties:
7340
+ type: string
7341
+ description: 'Per-chain-family daily spend in native major units (keys: evm, bitcoin, solana, xrp, cardano, tron).'
7161
7342
  api_key_expires_at:
7162
7343
  type: string
7163
7344
  format: date-time
@@ -7182,6 +7363,70 @@ components:
7182
7363
  items:
7183
7364
  $ref: "#/components/schemas/AgentSmartAccountResponse"
7184
7365
 
7366
+ KnownToken:
7367
+ type: object
7368
+ required: [id, chain, symbol, name, contract_address, decimals, is_testnet, is_verified]
7369
+ properties:
7370
+ id:
7371
+ type: string
7372
+ format: uuid
7373
+ chain:
7374
+ type: string
7375
+ symbol:
7376
+ type: string
7377
+ name:
7378
+ type: string
7379
+ contract_address:
7380
+ type: string
7381
+ decimals:
7382
+ type: integer
7383
+ is_testnet:
7384
+ type: boolean
7385
+ is_verified:
7386
+ type: boolean
7387
+ logo_url:
7388
+ type: string
7389
+ nullable: true
7390
+ created_at:
7391
+ type: string
7392
+ format: date-time
7393
+ updated_at:
7394
+ type: string
7395
+ format: date-time
7396
+
7397
+ KnownTokenListResponse:
7398
+ type: object
7399
+ required: [tokens]
7400
+ properties:
7401
+ tokens:
7402
+ type: array
7403
+ items:
7404
+ $ref: "#/components/schemas/KnownToken"
7405
+
7406
+ CreateKnownTokenRequest:
7407
+ type: object
7408
+ required: [chain, symbol, name, contract_address, decimals]
7409
+ properties:
7410
+ chain:
7411
+ type: string
7412
+ symbol:
7413
+ type: string
7414
+ name:
7415
+ type: string
7416
+ contract_address:
7417
+ type: string
7418
+ decimals:
7419
+ type: integer
7420
+ is_testnet:
7421
+ type: boolean
7422
+ default: false
7423
+ is_verified:
7424
+ type: boolean
7425
+ default: true
7426
+ logo_url:
7427
+ type: string
7428
+ nullable: true
7429
+
7185
7430
  AgentSmartAccountResponse:
7186
7431
  type: object
7187
7432
  description: One Safe smart account per chain for an agent
@@ -9473,6 +9718,22 @@ components:
9473
9718
  type: string
9474
9719
  balance_display:
9475
9720
  type: string
9721
+ tokens:
9722
+ type: array
9723
+ description: Token balances when ?tokens= query param is provided
9724
+ items:
9725
+ type: object
9726
+ properties:
9727
+ contract_address:
9728
+ type: string
9729
+ symbol:
9730
+ type: string
9731
+ nullable: true
9732
+ balance:
9733
+ type: string
9734
+ decimals:
9735
+ type: integer
9736
+ nullable: true
9476
9737
 
9477
9738
  # --- x402 ---
9478
9739
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@1claw/openapi-spec",
3
- "version": "0.37.0",
4
- "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API — generate clients in any language",
3
+ "version": "0.39.0",
4
+ "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API \u2014 generate clients in any language",
5
5
  "license": "MIT",
6
6
  "repository": {
7
7
  "type": "git",