@1claw/openapi-spec 0.37.0 → 0.38.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 (3) hide show
  1. package/openapi.json +346 -0
  2. package/openapi.yaml +227 -0
  3. package/package.json +1 -1
package/openapi.json CHANGED
@@ -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": {
@@ -10779,6 +10919,30 @@
10779
10919
  "shroud_config": {
10780
10920
  "$ref": "#/components/schemas/ShroudConfig"
10781
10921
  },
10922
+ "tx_token_allowlist": {
10923
+ "type": "array",
10924
+ "items": {
10925
+ "type": "string"
10926
+ },
10927
+ "description": "Token contract/mint addresses this agent may interact with. Empty = unrestricted."
10928
+ },
10929
+ "tx_known_tokens_only": {
10930
+ "type": "boolean",
10931
+ "default": false,
10932
+ "description": "When true, only tokens in the known_tokens registry may be used."
10933
+ },
10934
+ "xrpl_allowed_tx_types": {
10935
+ "type": "array",
10936
+ "items": {
10937
+ "type": "string"
10938
+ },
10939
+ "description": "Allowed XRP Ledger transaction types (Payment, TrustSet, etc.). Empty = all allowed."
10940
+ },
10941
+ "per_chain_guardrails": {
10942
+ "type": "object",
10943
+ "additionalProperties": true,
10944
+ "description": "Per-chain guardrail overrides. Keys are chain family names (ethereum, bitcoin, solana, etc.).\nEach value can contain: max_value, daily_limit, to_allowlist, token_allowlist.\nExample: { \"ethereum\": { \"max_value\": \"0.5\", \"to_allowlist\": [\"0x...\"] } }\n"
10945
+ },
10782
10946
  "api_key_expires_at": {
10783
10947
  "type": "string",
10784
10948
  "format": "date-time",
@@ -10864,6 +11028,30 @@
10864
11028
  "nullable": true,
10865
11029
  "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
11030
  },
11031
+ "tx_token_allowlist": {
11032
+ "type": "array",
11033
+ "items": {
11034
+ "type": "string"
11035
+ },
11036
+ "description": "Token contract/mint addresses this agent may interact with. Empty = unrestricted."
11037
+ },
11038
+ "tx_known_tokens_only": {
11039
+ "type": "boolean",
11040
+ "default": false,
11041
+ "description": "When true, only tokens in the known_tokens registry may be used."
11042
+ },
11043
+ "xrpl_allowed_tx_types": {
11044
+ "type": "array",
11045
+ "items": {
11046
+ "type": "string"
11047
+ },
11048
+ "description": "Allowed XRP Ledger transaction types (Payment, TrustSet, etc.). Empty = all allowed."
11049
+ },
11050
+ "per_chain_guardrails": {
11051
+ "type": "object",
11052
+ "additionalProperties": true,
11053
+ "description": "Per-chain guardrail overrides. Keys are chain family names (ethereum, bitcoin, solana, etc.).\nEach value can contain: max_value, daily_limit, to_allowlist, token_allowlist.\nExample: { \"ethereum\": { \"max_value\": \"0.5\", \"to_allowlist\": [\"0x...\"] } }\n"
11054
+ },
10867
11055
  "api_key_expires_at": {
10868
11056
  "type": "string",
10869
11057
  "format": "date-time",
@@ -11021,6 +11209,36 @@
11021
11209
  "type": "boolean",
11022
11210
  "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
11211
  },
11212
+ "tx_token_allowlist": {
11213
+ "type": "array",
11214
+ "items": {
11215
+ "type": "string"
11216
+ },
11217
+ "description": "Token contract/mint addresses this agent may interact with."
11218
+ },
11219
+ "tx_known_tokens_only": {
11220
+ "type": "boolean",
11221
+ "description": "When true, only tokens in the known_tokens registry may be used."
11222
+ },
11223
+ "xrpl_allowed_tx_types": {
11224
+ "type": "array",
11225
+ "items": {
11226
+ "type": "string"
11227
+ },
11228
+ "description": "Allowed XRP Ledger transaction types."
11229
+ },
11230
+ "per_chain_guardrails": {
11231
+ "type": "object",
11232
+ "additionalProperties": true,
11233
+ "description": "Per-chain guardrail overrides."
11234
+ },
11235
+ "tx_spent_today_by_chain": {
11236
+ "type": "object",
11237
+ "additionalProperties": {
11238
+ "type": "string"
11239
+ },
11240
+ "description": "Per-chain-family daily spend in major units (e.g. {\"ethereum\": \"0.5\", \"solana\": \"2.1\"})."
11241
+ },
11024
11242
  "api_key_expires_at": {
11025
11243
  "type": "string",
11026
11244
  "format": "date-time",
@@ -11053,6 +11271,111 @@
11053
11271
  }
11054
11272
  }
11055
11273
  },
11274
+ "KnownToken": {
11275
+ "type": "object",
11276
+ "required": [
11277
+ "id",
11278
+ "chain",
11279
+ "symbol",
11280
+ "name",
11281
+ "contract_address",
11282
+ "decimals",
11283
+ "is_testnet",
11284
+ "is_verified"
11285
+ ],
11286
+ "properties": {
11287
+ "id": {
11288
+ "type": "string",
11289
+ "format": "uuid"
11290
+ },
11291
+ "chain": {
11292
+ "type": "string"
11293
+ },
11294
+ "symbol": {
11295
+ "type": "string"
11296
+ },
11297
+ "name": {
11298
+ "type": "string"
11299
+ },
11300
+ "contract_address": {
11301
+ "type": "string"
11302
+ },
11303
+ "decimals": {
11304
+ "type": "integer"
11305
+ },
11306
+ "is_testnet": {
11307
+ "type": "boolean"
11308
+ },
11309
+ "is_verified": {
11310
+ "type": "boolean"
11311
+ },
11312
+ "logo_url": {
11313
+ "type": "string",
11314
+ "nullable": true
11315
+ },
11316
+ "created_at": {
11317
+ "type": "string",
11318
+ "format": "date-time"
11319
+ },
11320
+ "updated_at": {
11321
+ "type": "string",
11322
+ "format": "date-time"
11323
+ }
11324
+ }
11325
+ },
11326
+ "KnownTokenListResponse": {
11327
+ "type": "object",
11328
+ "required": [
11329
+ "tokens"
11330
+ ],
11331
+ "properties": {
11332
+ "tokens": {
11333
+ "type": "array",
11334
+ "items": {
11335
+ "$ref": "#/components/schemas/KnownToken"
11336
+ }
11337
+ }
11338
+ }
11339
+ },
11340
+ "CreateKnownTokenRequest": {
11341
+ "type": "object",
11342
+ "required": [
11343
+ "chain",
11344
+ "symbol",
11345
+ "name",
11346
+ "contract_address",
11347
+ "decimals"
11348
+ ],
11349
+ "properties": {
11350
+ "chain": {
11351
+ "type": "string"
11352
+ },
11353
+ "symbol": {
11354
+ "type": "string"
11355
+ },
11356
+ "name": {
11357
+ "type": "string"
11358
+ },
11359
+ "contract_address": {
11360
+ "type": "string"
11361
+ },
11362
+ "decimals": {
11363
+ "type": "integer"
11364
+ },
11365
+ "is_testnet": {
11366
+ "type": "boolean",
11367
+ "default": false
11368
+ },
11369
+ "is_verified": {
11370
+ "type": "boolean",
11371
+ "default": true
11372
+ },
11373
+ "logo_url": {
11374
+ "type": "string",
11375
+ "nullable": true
11376
+ }
11377
+ }
11378
+ },
11056
11379
  "AgentSmartAccountResponse": {
11057
11380
  "type": "object",
11058
11381
  "description": "One Safe smart account per chain for an agent",
@@ -14367,6 +14690,29 @@
14367
14690
  },
14368
14691
  "balance_display": {
14369
14692
  "type": "string"
14693
+ },
14694
+ "tokens": {
14695
+ "type": "array",
14696
+ "description": "Token balances when ?tokens= query param is provided",
14697
+ "items": {
14698
+ "type": "object",
14699
+ "properties": {
14700
+ "contract_address": {
14701
+ "type": "string"
14702
+ },
14703
+ "symbol": {
14704
+ "type": "string",
14705
+ "nullable": true
14706
+ },
14707
+ "balance": {
14708
+ "type": "string"
14709
+ },
14710
+ "decimals": {
14711
+ "type": "integer",
14712
+ "nullable": true
14713
+ }
14714
+ }
14715
+ }
14370
14716
  }
14371
14717
  }
14372
14718
  },
package/openapi.yaml CHANGED
@@ -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
  # =============================================================================
@@ -6969,6 +7052,27 @@ components:
6969
7052
  description: Enable Shroud LLM Proxy for this agent
6970
7053
  shroud_config:
6971
7054
  $ref: "#/components/schemas/ShroudConfig"
7055
+ tx_token_allowlist:
7056
+ type: array
7057
+ items:
7058
+ type: string
7059
+ description: Token contract/mint addresses this agent may interact with. Empty = unrestricted.
7060
+ tx_known_tokens_only:
7061
+ type: boolean
7062
+ default: false
7063
+ description: When true, only tokens in the known_tokens registry may be used.
7064
+ xrpl_allowed_tx_types:
7065
+ type: array
7066
+ items:
7067
+ type: string
7068
+ description: Allowed XRP Ledger transaction types (Payment, TrustSet, etc.). Empty = all allowed.
7069
+ per_chain_guardrails:
7070
+ type: object
7071
+ additionalProperties: true
7072
+ description: |
7073
+ Per-chain guardrail overrides. Keys are chain family names (ethereum, bitcoin, solana, etc.).
7074
+ Each value can contain: max_value, daily_limit, to_allowlist, token_allowlist.
7075
+ Example: { "ethereum": { "max_value": "0.5", "to_allowlist": ["0x..."] } }
6972
7076
  api_key_expires_at:
6973
7077
  type: string
6974
7078
  format: date-time
@@ -7040,6 +7144,27 @@ components:
7040
7144
  Per-agent TTL override for federation tokens (seconds). NULL falls
7041
7145
  back to the global default (`ONECLAW_JWT_FEDERATED_TOKEN_EXPIRY_SECS`).
7042
7146
  Hard-capped at 3600 seconds.
7147
+ tx_token_allowlist:
7148
+ type: array
7149
+ items:
7150
+ type: string
7151
+ description: Token contract/mint addresses this agent may interact with. Empty = unrestricted.
7152
+ tx_known_tokens_only:
7153
+ type: boolean
7154
+ default: false
7155
+ description: When true, only tokens in the known_tokens registry may be used.
7156
+ xrpl_allowed_tx_types:
7157
+ type: array
7158
+ items:
7159
+ type: string
7160
+ description: Allowed XRP Ledger transaction types (Payment, TrustSet, etc.). Empty = all allowed.
7161
+ per_chain_guardrails:
7162
+ type: object
7163
+ additionalProperties: true
7164
+ description: |
7165
+ Per-chain guardrail overrides. Keys are chain family names (ethereum, bitcoin, solana, etc.).
7166
+ Each value can contain: max_value, daily_limit, to_allowlist, token_allowlist.
7167
+ Example: { "ethereum": { "max_value": "0.5", "to_allowlist": ["0x..."] } }
7043
7168
  api_key_expires_at:
7044
7169
  type: string
7045
7170
  format: date-time
@@ -7158,6 +7283,28 @@ components:
7158
7283
  Whether the raw/precomputed-digest signing intent (eip712_digest) is
7159
7284
  enabled. Blind signing — bypasses transaction guardrails; OFF by default
7160
7285
  and human-set. Required for ERC-1271/ERC-7739 flows (e.g. Polymarket).
7286
+ tx_token_allowlist:
7287
+ type: array
7288
+ items:
7289
+ type: string
7290
+ description: Token contract/mint addresses this agent may interact with.
7291
+ tx_known_tokens_only:
7292
+ type: boolean
7293
+ description: When true, only tokens in the known_tokens registry may be used.
7294
+ xrpl_allowed_tx_types:
7295
+ type: array
7296
+ items:
7297
+ type: string
7298
+ description: Allowed XRP Ledger transaction types.
7299
+ per_chain_guardrails:
7300
+ type: object
7301
+ additionalProperties: true
7302
+ description: Per-chain guardrail overrides.
7303
+ tx_spent_today_by_chain:
7304
+ type: object
7305
+ additionalProperties:
7306
+ type: string
7307
+ description: 'Per-chain-family daily spend in major units (e.g. {"ethereum": "0.5", "solana": "2.1"}).'
7161
7308
  api_key_expires_at:
7162
7309
  type: string
7163
7310
  format: date-time
@@ -7182,6 +7329,70 @@ components:
7182
7329
  items:
7183
7330
  $ref: "#/components/schemas/AgentSmartAccountResponse"
7184
7331
 
7332
+ KnownToken:
7333
+ type: object
7334
+ required: [id, chain, symbol, name, contract_address, decimals, is_testnet, is_verified]
7335
+ properties:
7336
+ id:
7337
+ type: string
7338
+ format: uuid
7339
+ chain:
7340
+ type: string
7341
+ symbol:
7342
+ type: string
7343
+ name:
7344
+ type: string
7345
+ contract_address:
7346
+ type: string
7347
+ decimals:
7348
+ type: integer
7349
+ is_testnet:
7350
+ type: boolean
7351
+ is_verified:
7352
+ type: boolean
7353
+ logo_url:
7354
+ type: string
7355
+ nullable: true
7356
+ created_at:
7357
+ type: string
7358
+ format: date-time
7359
+ updated_at:
7360
+ type: string
7361
+ format: date-time
7362
+
7363
+ KnownTokenListResponse:
7364
+ type: object
7365
+ required: [tokens]
7366
+ properties:
7367
+ tokens:
7368
+ type: array
7369
+ items:
7370
+ $ref: "#/components/schemas/KnownToken"
7371
+
7372
+ CreateKnownTokenRequest:
7373
+ type: object
7374
+ required: [chain, symbol, name, contract_address, decimals]
7375
+ properties:
7376
+ chain:
7377
+ type: string
7378
+ symbol:
7379
+ type: string
7380
+ name:
7381
+ type: string
7382
+ contract_address:
7383
+ type: string
7384
+ decimals:
7385
+ type: integer
7386
+ is_testnet:
7387
+ type: boolean
7388
+ default: false
7389
+ is_verified:
7390
+ type: boolean
7391
+ default: true
7392
+ logo_url:
7393
+ type: string
7394
+ nullable: true
7395
+
7185
7396
  AgentSmartAccountResponse:
7186
7397
  type: object
7187
7398
  description: One Safe smart account per chain for an agent
@@ -9473,6 +9684,22 @@ components:
9473
9684
  type: string
9474
9685
  balance_display:
9475
9686
  type: string
9687
+ tokens:
9688
+ type: array
9689
+ description: Token balances when ?tokens= query param is provided
9690
+ items:
9691
+ type: object
9692
+ properties:
9693
+ contract_address:
9694
+ type: string
9695
+ symbol:
9696
+ type: string
9697
+ nullable: true
9698
+ balance:
9699
+ type: string
9700
+ decimals:
9701
+ type: integer
9702
+ nullable: true
9476
9703
 
9477
9704
  # --- x402 ---
9478
9705
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@1claw/openapi-spec",
3
- "version": "0.37.0",
3
+ "version": "0.38.0",
4
4
  "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API — generate clients in any language",
5
5
  "license": "MIT",
6
6
  "repository": {