@1claw/openapi-spec 0.20.2 → 0.22.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 +4 -1
  2. package/openapi.json +728 -5
  3. package/openapi.yaml +481 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -40,16 +40,19 @@ openapi-generator generate \
40
40
  import spec from "@1claw/openapi-spec/openapi.json";
41
41
  ```
42
42
 
43
- ## What's in the spec (v0.20.x — API `info.version` 2.10.x)
43
+ ## What's in the spec (v0.21.x — API `info.version` 2.11.x)
44
44
 
45
45
  - **OIDC Federation (1claw as IdP)** — `GET /.well-known/openid-configuration` (public discovery: issuer, jwks_uri, supported algs `["EdDSA","RS256"]`, supported grant types incl. token-exchange), `GET /.well-known/jwks.json` (public JWKS — every active EdDSA + RS256 key version, keyed by deterministic `kid`), `POST /v1/auth/federated-token` (RFC 8693 token exchange — accepts JSON or `application/x-www-form-urlencoded`; subject token is an agent JWT or `ocv_` API key; returns RS256 JWT scoped to `audience`). Agent fields: `federation_enabled`, `federation_audiences[]`, `federated_token_ttl_seconds`. Designed for Anthropic Workload Identity Federation, GCP STS, AWS STS, etc.
46
46
  - **Auth — agent JWT** — `POST /v1/auth/agent-token` documents optional JWT claim **`shroud_config`** when the agent has Shroud enabled (mirrors DB; consumed by Shroud PolicyEngine on LLM requests). Re-exchange after changing agent Shroud settings. Federation tokens use a separate KMS RSA-2048 key and are signed RS256.
47
47
  - **Auth — password reset** — `POST /v1/auth/forgot-password`, `POST /v1/auth/reset-password` (public; anti-enumeration on forgot)
48
48
  - **Billing — LLM token billing** — `GET /v1/billing/llm-token-billing` (`LlmTokenBillingStatus`: `enabled`, `subscription_status`, optional `credit_balance`, optional `billing_cycle_usage` with `metered_lines[]`), `POST .../subscribe`, `POST .../disable` (Stripe AI Gateway add-on; optional org feature)
49
49
  - **Treasury** — Safe multisig treasuries: `POST/GET /v1/treasury`, `GET/PATCH/DELETE /v1/treasury/{id}`, signers, agent access requests (`requests[]` on list)
50
+ - **Treasury Wallets** — Multi-chain wallet generation for human users (replaces CDP embedded wallets): `POST /v1/treasury/wallets/generate`, `GET /v1/treasury/wallets`, `GET /v1/treasury/wallets/{chain}`, `POST .../export`, `POST .../rotate`, `DELETE /v1/treasury/wallets/{chain}`. Supported chains: ethereum, bitcoin, solana, xrp, cardano, tron. Private keys stored in per-org `__treasury-keys` vault with tier-appropriate MPC custody.
50
51
  - **Vaults** — CRUD, CMEK enable/disable, key rotation with job tracking, MPC enable/disable (`POST /v1/vaults/{id}/mpc`, `DELETE /v1/vaults/{id}/mpc`)
51
52
  - **Secrets** — CRUD, versioning, CMEK-encrypted flag, `client_share` in responses (MPC vaults)
52
53
  - **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
54
+ - **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
55
+ - **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)
53
56
  - **Policies** — Glob-based access control
54
57
  - **Sharing** — Links, user/agent shares, accept/decline
55
58
  - **Billing** — Subscriptions, credits, x402, LLM token billing (see above)
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.10.1",
5
+ "version": "2.12.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"
@@ -87,6 +87,10 @@
87
87
  "name": "Treasury",
88
88
  "description": "Multi-sig treasury wallets (Safe) and agent access requests"
89
89
  },
90
+ {
91
+ "name": "Treasury Wallets",
92
+ "description": "Multi-chain wallet generation for human users (replaces CDP embedded wallets)"
93
+ },
90
94
  {
91
95
  "name": "Admin",
92
96
  "description": "Platform administration"
@@ -2646,6 +2650,181 @@
2646
2650
  }
2647
2651
  }
2648
2652
  },
2653
+ "/v1/agents/{agent_id}/signing-keys": {
2654
+ "post": {
2655
+ "tags": [
2656
+ "Signing Keys"
2657
+ ],
2658
+ "summary": "Provision a signing key for a chain",
2659
+ "operationId": "createSigningKey",
2660
+ "parameters": [
2661
+ {
2662
+ "$ref": "#/components/parameters/AgentId"
2663
+ }
2664
+ ],
2665
+ "requestBody": {
2666
+ "required": true,
2667
+ "content": {
2668
+ "application/json": {
2669
+ "schema": {
2670
+ "$ref": "#/components/schemas/CreateSigningKeyRequest"
2671
+ }
2672
+ }
2673
+ }
2674
+ },
2675
+ "responses": {
2676
+ "201": {
2677
+ "description": "Signing key created",
2678
+ "content": {
2679
+ "application/json": {
2680
+ "schema": {
2681
+ "$ref": "#/components/schemas/SigningKeyResponse"
2682
+ }
2683
+ }
2684
+ }
2685
+ },
2686
+ "400": {
2687
+ "$ref": "#/components/responses/BadRequest"
2688
+ },
2689
+ "409": {
2690
+ "$ref": "#/components/responses/Conflict"
2691
+ }
2692
+ }
2693
+ },
2694
+ "get": {
2695
+ "tags": [
2696
+ "Signing Keys"
2697
+ ],
2698
+ "summary": "List signing keys for an agent",
2699
+ "operationId": "listSigningKeys",
2700
+ "parameters": [
2701
+ {
2702
+ "$ref": "#/components/parameters/AgentId"
2703
+ }
2704
+ ],
2705
+ "responses": {
2706
+ "200": {
2707
+ "description": "Signing keys list",
2708
+ "content": {
2709
+ "application/json": {
2710
+ "schema": {
2711
+ "$ref": "#/components/schemas/SigningKeyListResponse"
2712
+ }
2713
+ }
2714
+ }
2715
+ }
2716
+ }
2717
+ }
2718
+ },
2719
+ "/v1/agents/{agent_id}/signing-keys/{chain}/rotate": {
2720
+ "post": {
2721
+ "tags": [
2722
+ "Signing Keys"
2723
+ ],
2724
+ "summary": "Rotate a signing key for a chain",
2725
+ "operationId": "rotateSigningKey",
2726
+ "parameters": [
2727
+ {
2728
+ "$ref": "#/components/parameters/AgentId"
2729
+ },
2730
+ {
2731
+ "name": "chain",
2732
+ "in": "path",
2733
+ "required": true,
2734
+ "schema": {
2735
+ "type": "string"
2736
+ }
2737
+ }
2738
+ ],
2739
+ "responses": {
2740
+ "200": {
2741
+ "description": "Rotated signing key",
2742
+ "content": {
2743
+ "application/json": {
2744
+ "schema": {
2745
+ "$ref": "#/components/schemas/SigningKeyResponse"
2746
+ }
2747
+ }
2748
+ }
2749
+ },
2750
+ "404": {
2751
+ "$ref": "#/components/responses/NotFound"
2752
+ }
2753
+ }
2754
+ }
2755
+ },
2756
+ "/v1/agents/{agent_id}/signing-keys/{chain}": {
2757
+ "delete": {
2758
+ "tags": [
2759
+ "Signing Keys"
2760
+ ],
2761
+ "summary": "Deactivate a signing key for a chain",
2762
+ "operationId": "deactivateSigningKey",
2763
+ "parameters": [
2764
+ {
2765
+ "$ref": "#/components/parameters/AgentId"
2766
+ },
2767
+ {
2768
+ "name": "chain",
2769
+ "in": "path",
2770
+ "required": true,
2771
+ "schema": {
2772
+ "type": "string"
2773
+ }
2774
+ }
2775
+ ],
2776
+ "responses": {
2777
+ "204": {
2778
+ "description": "Key deactivated"
2779
+ },
2780
+ "404": {
2781
+ "$ref": "#/components/responses/NotFound"
2782
+ }
2783
+ }
2784
+ }
2785
+ },
2786
+ "/v1/agents/{agent_id}/sign": {
2787
+ "post": {
2788
+ "tags": [
2789
+ "Signing"
2790
+ ],
2791
+ "summary": "Unified signing intent (EIP-191, EIP-712, EIP-2718 types 0-4)",
2792
+ "operationId": "signIntent",
2793
+ "parameters": [
2794
+ {
2795
+ "$ref": "#/components/parameters/AgentId"
2796
+ }
2797
+ ],
2798
+ "requestBody": {
2799
+ "required": true,
2800
+ "content": {
2801
+ "application/json": {
2802
+ "schema": {
2803
+ "$ref": "#/components/schemas/SignIntentRequest"
2804
+ }
2805
+ }
2806
+ }
2807
+ },
2808
+ "responses": {
2809
+ "200": {
2810
+ "description": "Signed result",
2811
+ "content": {
2812
+ "application/json": {
2813
+ "schema": {
2814
+ "$ref": "#/components/schemas/SignIntentResponse"
2815
+ }
2816
+ }
2817
+ }
2818
+ },
2819
+ "400": {
2820
+ "$ref": "#/components/responses/BadRequest"
2821
+ },
2822
+ "403": {
2823
+ "$ref": "#/components/responses/Forbidden"
2824
+ }
2825
+ }
2826
+ }
2827
+ },
2649
2828
  "/v1/chains": {
2650
2829
  "get": {
2651
2830
  "tags": [
@@ -4107,18 +4286,270 @@
4107
4286
  }
4108
4287
  },
4109
4288
  {
4110
- "name": "request_id",
4289
+ "name": "request_id",
4290
+ "in": "path",
4291
+ "required": true,
4292
+ "schema": {
4293
+ "type": "string",
4294
+ "format": "uuid"
4295
+ }
4296
+ }
4297
+ ],
4298
+ "responses": {
4299
+ "200": {
4300
+ "description": "Access request denied"
4301
+ },
4302
+ "404": {
4303
+ "$ref": "#/components/responses/NotFound"
4304
+ }
4305
+ }
4306
+ }
4307
+ },
4308
+ "/v1/treasury/wallets/generate": {
4309
+ "post": {
4310
+ "tags": [
4311
+ "Treasury Wallets"
4312
+ ],
4313
+ "summary": "Generate multi-chain wallets for the authenticated user",
4314
+ "description": "Generates keypairs for the requested chains (or all supported chains if omitted).\nPrivate keys are stored in a per-org `__treasury-keys` vault with tier-appropriate\nMPC custody. Skips chains where the user already has an active wallet. Requires\nPro or higher billing tier. Human users only — agents get 403.\n",
4315
+ "operationId": "generateTreasuryWallets",
4316
+ "security": [
4317
+ {
4318
+ "BearerAuth": []
4319
+ }
4320
+ ],
4321
+ "requestBody": {
4322
+ "required": true,
4323
+ "content": {
4324
+ "application/json": {
4325
+ "schema": {
4326
+ "$ref": "#/components/schemas/GenerateTreasuryWalletsRequest"
4327
+ }
4328
+ }
4329
+ }
4330
+ },
4331
+ "responses": {
4332
+ "201": {
4333
+ "description": "Wallets generated",
4334
+ "content": {
4335
+ "application/json": {
4336
+ "schema": {
4337
+ "$ref": "#/components/schemas/TreasuryWalletListResponse"
4338
+ }
4339
+ }
4340
+ }
4341
+ },
4342
+ "400": {
4343
+ "$ref": "#/components/responses/BadRequest"
4344
+ },
4345
+ "401": {
4346
+ "$ref": "#/components/responses/Unauthorized"
4347
+ },
4348
+ "403": {
4349
+ "$ref": "#/components/responses/Forbidden"
4350
+ }
4351
+ }
4352
+ }
4353
+ },
4354
+ "/v1/treasury/wallets": {
4355
+ "get": {
4356
+ "tags": [
4357
+ "Treasury Wallets"
4358
+ ],
4359
+ "summary": "List the authenticated user's treasury wallets",
4360
+ "operationId": "listTreasuryWallets",
4361
+ "security": [
4362
+ {
4363
+ "BearerAuth": []
4364
+ }
4365
+ ],
4366
+ "responses": {
4367
+ "200": {
4368
+ "description": "Wallet list",
4369
+ "content": {
4370
+ "application/json": {
4371
+ "schema": {
4372
+ "$ref": "#/components/schemas/TreasuryWalletListResponse"
4373
+ }
4374
+ }
4375
+ }
4376
+ },
4377
+ "401": {
4378
+ "$ref": "#/components/responses/Unauthorized"
4379
+ },
4380
+ "403": {
4381
+ "$ref": "#/components/responses/Forbidden"
4382
+ }
4383
+ }
4384
+ }
4385
+ },
4386
+ "/v1/treasury/wallets/{chain}": {
4387
+ "get": {
4388
+ "tags": [
4389
+ "Treasury Wallets"
4390
+ ],
4391
+ "summary": "Get the user's active wallet for a specific chain",
4392
+ "operationId": "getTreasuryWallet",
4393
+ "security": [
4394
+ {
4395
+ "BearerAuth": []
4396
+ }
4397
+ ],
4398
+ "parameters": [
4399
+ {
4400
+ "name": "chain",
4401
+ "in": "path",
4402
+ "required": true,
4403
+ "schema": {
4404
+ "type": "string"
4405
+ },
4406
+ "description": "Chain name (e.g. ethereum, solana, bitcoin)"
4407
+ }
4408
+ ],
4409
+ "responses": {
4410
+ "200": {
4411
+ "description": "Wallet details",
4412
+ "content": {
4413
+ "application/json": {
4414
+ "schema": {
4415
+ "$ref": "#/components/schemas/TreasuryWalletResponse"
4416
+ }
4417
+ }
4418
+ }
4419
+ },
4420
+ "401": {
4421
+ "$ref": "#/components/responses/Unauthorized"
4422
+ },
4423
+ "403": {
4424
+ "$ref": "#/components/responses/Forbidden"
4425
+ },
4426
+ "404": {
4427
+ "$ref": "#/components/responses/NotFound"
4428
+ }
4429
+ }
4430
+ },
4431
+ "delete": {
4432
+ "tags": [
4433
+ "Treasury Wallets"
4434
+ ],
4435
+ "summary": "Deactivate the user's wallet for a specific chain",
4436
+ "operationId": "deactivateTreasuryWallet",
4437
+ "security": [
4438
+ {
4439
+ "BearerAuth": []
4440
+ }
4441
+ ],
4442
+ "parameters": [
4443
+ {
4444
+ "name": "chain",
4445
+ "in": "path",
4446
+ "required": true,
4447
+ "schema": {
4448
+ "type": "string"
4449
+ }
4450
+ }
4451
+ ],
4452
+ "responses": {
4453
+ "204": {
4454
+ "description": "Wallet deactivated"
4455
+ },
4456
+ "401": {
4457
+ "$ref": "#/components/responses/Unauthorized"
4458
+ },
4459
+ "403": {
4460
+ "$ref": "#/components/responses/Forbidden"
4461
+ }
4462
+ }
4463
+ }
4464
+ },
4465
+ "/v1/treasury/wallets/{chain}/export": {
4466
+ "post": {
4467
+ "tags": [
4468
+ "Treasury Wallets"
4469
+ ],
4470
+ "summary": "Export the private key for a treasury wallet",
4471
+ "description": "Returns the raw private key hex for the user's active wallet on\nthe given chain. Audit-logged as `treasury_wallet.export`.\nHuman users only.\n",
4472
+ "operationId": "exportTreasuryWallet",
4473
+ "security": [
4474
+ {
4475
+ "BearerAuth": []
4476
+ }
4477
+ ],
4478
+ "parameters": [
4479
+ {
4480
+ "name": "chain",
4481
+ "in": "path",
4482
+ "required": true,
4483
+ "schema": {
4484
+ "type": "string"
4485
+ }
4486
+ }
4487
+ ],
4488
+ "responses": {
4489
+ "200": {
4490
+ "description": "Private key exported",
4491
+ "content": {
4492
+ "application/json": {
4493
+ "schema": {
4494
+ "$ref": "#/components/schemas/TreasuryWalletExportResponse"
4495
+ }
4496
+ }
4497
+ }
4498
+ },
4499
+ "401": {
4500
+ "$ref": "#/components/responses/Unauthorized"
4501
+ },
4502
+ "403": {
4503
+ "$ref": "#/components/responses/Forbidden"
4504
+ },
4505
+ "404": {
4506
+ "$ref": "#/components/responses/NotFound"
4507
+ }
4508
+ }
4509
+ }
4510
+ },
4511
+ "/v1/treasury/wallets/{chain}/rotate": {
4512
+ "post": {
4513
+ "tags": [
4514
+ "Treasury Wallets"
4515
+ ],
4516
+ "summary": "Rotate the user's wallet key for a chain",
4517
+ "description": "Generates a new keypair, deactivates the old wallet, and creates a\nnew active wallet. The old private key version is retained in the\nvault for audit. Requires Pro or higher.\n",
4518
+ "operationId": "rotateTreasuryWallet",
4519
+ "security": [
4520
+ {
4521
+ "BearerAuth": []
4522
+ }
4523
+ ],
4524
+ "parameters": [
4525
+ {
4526
+ "name": "chain",
4111
4527
  "in": "path",
4112
4528
  "required": true,
4113
4529
  "schema": {
4114
- "type": "string",
4115
- "format": "uuid"
4530
+ "type": "string"
4116
4531
  }
4117
4532
  }
4118
4533
  ],
4119
4534
  "responses": {
4120
4535
  "200": {
4121
- "description": "Access request denied"
4536
+ "description": "Wallet rotated",
4537
+ "content": {
4538
+ "application/json": {
4539
+ "schema": {
4540
+ "$ref": "#/components/schemas/TreasuryWalletResponse"
4541
+ }
4542
+ }
4543
+ }
4544
+ },
4545
+ "400": {
4546
+ "$ref": "#/components/responses/BadRequest"
4547
+ },
4548
+ "401": {
4549
+ "$ref": "#/components/responses/Unauthorized"
4550
+ },
4551
+ "403": {
4552
+ "$ref": "#/components/responses/Forbidden"
4122
4553
  },
4123
4554
  "404": {
4124
4555
  "$ref": "#/components/responses/NotFound"
@@ -4808,6 +5239,16 @@
4808
5239
  }
4809
5240
  }
4810
5241
  }
5242
+ },
5243
+ "Conflict": {
5244
+ "description": "Resource already exists or conflict",
5245
+ "content": {
5246
+ "application/json": {
5247
+ "schema": {
5248
+ "$ref": "#/components/schemas/ProblemDetails"
5249
+ }
5250
+ }
5251
+ }
4811
5252
  }
4812
5253
  },
4813
5254
  "schemas": {
@@ -6264,6 +6705,32 @@
6264
6705
  "nullable": true,
6265
6706
  "description": "Per-agent TTL override for federation tokens (60..=3600)."
6266
6707
  },
6708
+ "signing_chains": {
6709
+ "type": "array",
6710
+ "items": {
6711
+ "type": "string"
6712
+ },
6713
+ "description": "Chains for which this agent has provisioned signing keys."
6714
+ },
6715
+ "eip712_domain_allowlist": {
6716
+ "type": "array",
6717
+ "items": {
6718
+ "type": "object"
6719
+ },
6720
+ "description": "JSON array of allowed EIP-712 domain entries."
6721
+ },
6722
+ "eip712_default_policy": {
6723
+ "type": "string",
6724
+ "enum": [
6725
+ "deny",
6726
+ "allow"
6727
+ ],
6728
+ "description": "Default EIP-712 policy (deny blocks all unless allowlisted)."
6729
+ },
6730
+ "message_signing_enabled": {
6731
+ "type": "boolean",
6732
+ "description": "Whether EIP-191 personal_sign is enabled."
6733
+ },
6267
6734
  "created_at": {
6268
6735
  "type": "string",
6269
6736
  "format": "date-time"
@@ -7181,6 +7648,195 @@
7181
7648
  }
7182
7649
  }
7183
7650
  },
7651
+ "CreateSigningKeyRequest": {
7652
+ "type": "object",
7653
+ "required": [
7654
+ "chain"
7655
+ ],
7656
+ "properties": {
7657
+ "chain": {
7658
+ "type": "string",
7659
+ "enum": [
7660
+ "ethereum",
7661
+ "bitcoin",
7662
+ "solana",
7663
+ "xrp",
7664
+ "cardano",
7665
+ "tron"
7666
+ ]
7667
+ }
7668
+ }
7669
+ },
7670
+ "SigningKeyResponse": {
7671
+ "type": "object",
7672
+ "properties": {
7673
+ "id": {
7674
+ "type": "string",
7675
+ "format": "uuid"
7676
+ },
7677
+ "agent_id": {
7678
+ "type": "string",
7679
+ "format": "uuid"
7680
+ },
7681
+ "chain": {
7682
+ "type": "string"
7683
+ },
7684
+ "curve": {
7685
+ "type": "string"
7686
+ },
7687
+ "public_key": {
7688
+ "type": "string"
7689
+ },
7690
+ "address": {
7691
+ "type": "string",
7692
+ "nullable": true
7693
+ },
7694
+ "key_version": {
7695
+ "type": "integer"
7696
+ },
7697
+ "is_active": {
7698
+ "type": "boolean"
7699
+ },
7700
+ "created_at": {
7701
+ "type": "string",
7702
+ "format": "date-time"
7703
+ },
7704
+ "rotated_at": {
7705
+ "type": "string",
7706
+ "format": "date-time",
7707
+ "nullable": true
7708
+ }
7709
+ }
7710
+ },
7711
+ "SigningKeyListResponse": {
7712
+ "type": "object",
7713
+ "properties": {
7714
+ "keys": {
7715
+ "type": "array",
7716
+ "items": {
7717
+ "$ref": "#/components/schemas/SigningKeyResponse"
7718
+ }
7719
+ }
7720
+ }
7721
+ },
7722
+ "SignIntentRequest": {
7723
+ "type": "object",
7724
+ "required": [
7725
+ "intent_type",
7726
+ "chain"
7727
+ ],
7728
+ "properties": {
7729
+ "intent_type": {
7730
+ "type": "string",
7731
+ "enum": [
7732
+ "personal_sign",
7733
+ "typed_data",
7734
+ "transaction"
7735
+ ]
7736
+ },
7737
+ "chain": {
7738
+ "type": "string"
7739
+ },
7740
+ "signing_key_path": {
7741
+ "type": "string"
7742
+ },
7743
+ "message": {
7744
+ "type": "string",
7745
+ "description": "Hex-encoded message bytes (for personal_sign)"
7746
+ },
7747
+ "typed_data": {
7748
+ "type": "object",
7749
+ "description": "EIP-712 typed data JSON (for typed_data)"
7750
+ },
7751
+ "tx_type": {
7752
+ "type": "integer",
7753
+ "description": "EIP-2718 type: 0=legacy, 1=2930, 2=1559, 3=4844, 4=7702"
7754
+ },
7755
+ "to": {
7756
+ "type": "string"
7757
+ },
7758
+ "value": {
7759
+ "type": "string"
7760
+ },
7761
+ "data": {
7762
+ "type": "string"
7763
+ },
7764
+ "nonce": {
7765
+ "type": "integer"
7766
+ },
7767
+ "gas_limit": {
7768
+ "type": "integer"
7769
+ },
7770
+ "gas_price": {
7771
+ "type": "string"
7772
+ },
7773
+ "max_fee_per_gas": {
7774
+ "type": "string"
7775
+ },
7776
+ "max_priority_fee_per_gas": {
7777
+ "type": "string"
7778
+ },
7779
+ "access_list": {
7780
+ "type": "array",
7781
+ "items": {
7782
+ "type": "object"
7783
+ }
7784
+ },
7785
+ "max_fee_per_blob_gas": {
7786
+ "type": "string"
7787
+ },
7788
+ "blob_versioned_hashes": {
7789
+ "type": "array",
7790
+ "items": {
7791
+ "type": "string"
7792
+ }
7793
+ },
7794
+ "authorization_list": {
7795
+ "type": "array",
7796
+ "items": {
7797
+ "type": "object"
7798
+ }
7799
+ }
7800
+ }
7801
+ },
7802
+ "SignIntentResponse": {
7803
+ "type": "object",
7804
+ "properties": {
7805
+ "intent_type": {
7806
+ "type": "string"
7807
+ },
7808
+ "chain": {
7809
+ "type": "string"
7810
+ },
7811
+ "from": {
7812
+ "type": "string"
7813
+ },
7814
+ "signature": {
7815
+ "type": "string",
7816
+ "nullable": true
7817
+ },
7818
+ "signed_tx": {
7819
+ "type": "string",
7820
+ "nullable": true
7821
+ },
7822
+ "tx_hash": {
7823
+ "type": "string",
7824
+ "nullable": true
7825
+ },
7826
+ "message_hash": {
7827
+ "type": "string",
7828
+ "nullable": true
7829
+ },
7830
+ "typed_data_hash": {
7831
+ "type": "string",
7832
+ "nullable": true
7833
+ },
7834
+ "tx_type": {
7835
+ "type": "integer",
7836
+ "nullable": true
7837
+ }
7838
+ }
7839
+ },
7184
7840
  "TransactionResponse": {
7185
7841
  "type": "object",
7186
7842
  "properties": {
@@ -8578,6 +9234,73 @@
8578
9234
  }
8579
9235
  }
8580
9236
  },
9237
+ "GenerateTreasuryWalletsRequest": {
9238
+ "type": "object",
9239
+ "properties": {
9240
+ "chains": {
9241
+ "type": "array",
9242
+ "items": {
9243
+ "type": "string"
9244
+ },
9245
+ "description": "Chains to generate wallets for (e.g. [\"ethereum\", \"solana\"]). Omit for all supported chains."
9246
+ }
9247
+ }
9248
+ },
9249
+ "TreasuryWalletResponse": {
9250
+ "type": "object",
9251
+ "properties": {
9252
+ "id": {
9253
+ "type": "string",
9254
+ "format": "uuid"
9255
+ },
9256
+ "chain": {
9257
+ "type": "string"
9258
+ },
9259
+ "curve": {
9260
+ "type": "string",
9261
+ "description": "Cryptographic curve (e.g. secp256k1, ed25519)"
9262
+ },
9263
+ "public_key_hex": {
9264
+ "type": "string"
9265
+ },
9266
+ "address": {
9267
+ "type": "string"
9268
+ },
9269
+ "is_active": {
9270
+ "type": "boolean"
9271
+ },
9272
+ "created_at": {
9273
+ "type": "string",
9274
+ "format": "date-time"
9275
+ }
9276
+ }
9277
+ },
9278
+ "TreasuryWalletListResponse": {
9279
+ "type": "object",
9280
+ "properties": {
9281
+ "wallets": {
9282
+ "type": "array",
9283
+ "items": {
9284
+ "$ref": "#/components/schemas/TreasuryWalletResponse"
9285
+ }
9286
+ }
9287
+ }
9288
+ },
9289
+ "TreasuryWalletExportResponse": {
9290
+ "type": "object",
9291
+ "properties": {
9292
+ "chain": {
9293
+ "type": "string"
9294
+ },
9295
+ "address": {
9296
+ "type": "string"
9297
+ },
9298
+ "private_key_hex": {
9299
+ "type": "string",
9300
+ "description": "Raw private key in hex encoding. Handle with extreme care."
9301
+ }
9302
+ }
9303
+ },
8581
9304
  "PaymentRequirement": {
8582
9305
  "type": "object",
8583
9306
  "properties": {
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.10.1
5
+ version: 2.12.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,
@@ -56,6 +56,8 @@ tags:
56
56
  description: IP rules and security configuration
57
57
  - name: Treasury
58
58
  description: Multi-sig treasury wallets (Safe) and agent access requests
59
+ - name: Treasury Wallets
60
+ description: Multi-chain wallet generation for human users (replaces CDP embedded wallets)
59
61
  - name: Admin
60
62
  description: Platform administration
61
63
  - name: Health
@@ -1759,6 +1761,117 @@ paths:
1759
1761
  "402":
1760
1762
  $ref: "#/components/responses/PaymentRequired"
1761
1763
 
1764
+ # ---------------------------------------------------------------------------
1765
+ # Agent Signing Keys (Multi-Chain)
1766
+ # ---------------------------------------------------------------------------
1767
+
1768
+ /v1/agents/{agent_id}/signing-keys:
1769
+ post:
1770
+ tags: [Signing Keys]
1771
+ summary: Provision a signing key for a chain
1772
+ operationId: createSigningKey
1773
+ parameters:
1774
+ - $ref: "#/components/parameters/AgentId"
1775
+ requestBody:
1776
+ required: true
1777
+ content:
1778
+ application/json:
1779
+ schema:
1780
+ $ref: "#/components/schemas/CreateSigningKeyRequest"
1781
+ responses:
1782
+ "201":
1783
+ description: Signing key created
1784
+ content:
1785
+ application/json:
1786
+ schema:
1787
+ $ref: "#/components/schemas/SigningKeyResponse"
1788
+ "400":
1789
+ $ref: "#/components/responses/BadRequest"
1790
+ "409":
1791
+ $ref: "#/components/responses/Conflict"
1792
+ get:
1793
+ tags: [Signing Keys]
1794
+ summary: List signing keys for an agent
1795
+ operationId: listSigningKeys
1796
+ parameters:
1797
+ - $ref: "#/components/parameters/AgentId"
1798
+ responses:
1799
+ "200":
1800
+ description: Signing keys list
1801
+ content:
1802
+ application/json:
1803
+ schema:
1804
+ $ref: "#/components/schemas/SigningKeyListResponse"
1805
+
1806
+ /v1/agents/{agent_id}/signing-keys/{chain}/rotate:
1807
+ post:
1808
+ tags: [Signing Keys]
1809
+ summary: Rotate a signing key for a chain
1810
+ operationId: rotateSigningKey
1811
+ parameters:
1812
+ - $ref: "#/components/parameters/AgentId"
1813
+ - name: chain
1814
+ in: path
1815
+ required: true
1816
+ schema:
1817
+ type: string
1818
+ responses:
1819
+ "200":
1820
+ description: Rotated signing key
1821
+ content:
1822
+ application/json:
1823
+ schema:
1824
+ $ref: "#/components/schemas/SigningKeyResponse"
1825
+ "404":
1826
+ $ref: "#/components/responses/NotFound"
1827
+
1828
+ /v1/agents/{agent_id}/signing-keys/{chain}:
1829
+ delete:
1830
+ tags: [Signing Keys]
1831
+ summary: Deactivate a signing key for a chain
1832
+ operationId: deactivateSigningKey
1833
+ parameters:
1834
+ - $ref: "#/components/parameters/AgentId"
1835
+ - name: chain
1836
+ in: path
1837
+ required: true
1838
+ schema:
1839
+ type: string
1840
+ responses:
1841
+ "204":
1842
+ description: Key deactivated
1843
+ "404":
1844
+ $ref: "#/components/responses/NotFound"
1845
+
1846
+ # ---------------------------------------------------------------------------
1847
+ # Unified Signing Intent
1848
+ # ---------------------------------------------------------------------------
1849
+
1850
+ /v1/agents/{agent_id}/sign:
1851
+ post:
1852
+ tags: [Signing]
1853
+ summary: Unified signing intent (EIP-191, EIP-712, EIP-2718 types 0-4)
1854
+ operationId: signIntent
1855
+ parameters:
1856
+ - $ref: "#/components/parameters/AgentId"
1857
+ requestBody:
1858
+ required: true
1859
+ content:
1860
+ application/json:
1861
+ schema:
1862
+ $ref: "#/components/schemas/SignIntentRequest"
1863
+ responses:
1864
+ "200":
1865
+ description: Signed result
1866
+ content:
1867
+ application/json:
1868
+ schema:
1869
+ $ref: "#/components/schemas/SignIntentResponse"
1870
+ "400":
1871
+ $ref: "#/components/responses/BadRequest"
1872
+ "403":
1873
+ $ref: "#/components/responses/Forbidden"
1874
+
1762
1875
  # ---------------------------------------------------------------------------
1763
1876
  # Chains
1764
1877
  # ---------------------------------------------------------------------------
@@ -2708,6 +2821,172 @@ paths:
2708
2821
  "404":
2709
2822
  $ref: "#/components/responses/NotFound"
2710
2823
 
2824
+ # ---------------------------------------------------------------------------
2825
+ # Treasury Wallets (multi-chain key generation for human users)
2826
+ # ---------------------------------------------------------------------------
2827
+
2828
+ /v1/treasury/wallets/generate:
2829
+ post:
2830
+ tags: [Treasury Wallets]
2831
+ summary: Generate multi-chain wallets for the authenticated user
2832
+ description: |
2833
+ Generates keypairs for the requested chains (or all supported chains if omitted).
2834
+ Private keys are stored in a per-org `__treasury-keys` vault with tier-appropriate
2835
+ MPC custody. Skips chains where the user already has an active wallet. Requires
2836
+ Pro or higher billing tier. Human users only — agents get 403.
2837
+ operationId: generateTreasuryWallets
2838
+ security:
2839
+ - BearerAuth: []
2840
+ requestBody:
2841
+ required: true
2842
+ content:
2843
+ application/json:
2844
+ schema:
2845
+ $ref: "#/components/schemas/GenerateTreasuryWalletsRequest"
2846
+ responses:
2847
+ "201":
2848
+ description: Wallets generated
2849
+ content:
2850
+ application/json:
2851
+ schema:
2852
+ $ref: "#/components/schemas/TreasuryWalletListResponse"
2853
+ "400":
2854
+ $ref: "#/components/responses/BadRequest"
2855
+ "401":
2856
+ $ref: "#/components/responses/Unauthorized"
2857
+ "403":
2858
+ $ref: "#/components/responses/Forbidden"
2859
+
2860
+ /v1/treasury/wallets:
2861
+ get:
2862
+ tags: [Treasury Wallets]
2863
+ summary: List the authenticated user's treasury wallets
2864
+ operationId: listTreasuryWallets
2865
+ security:
2866
+ - BearerAuth: []
2867
+ responses:
2868
+ "200":
2869
+ description: Wallet list
2870
+ content:
2871
+ application/json:
2872
+ schema:
2873
+ $ref: "#/components/schemas/TreasuryWalletListResponse"
2874
+ "401":
2875
+ $ref: "#/components/responses/Unauthorized"
2876
+ "403":
2877
+ $ref: "#/components/responses/Forbidden"
2878
+
2879
+ /v1/treasury/wallets/{chain}:
2880
+ get:
2881
+ tags: [Treasury Wallets]
2882
+ summary: Get the user's active wallet for a specific chain
2883
+ operationId: getTreasuryWallet
2884
+ security:
2885
+ - BearerAuth: []
2886
+ parameters:
2887
+ - name: chain
2888
+ in: path
2889
+ required: true
2890
+ schema:
2891
+ type: string
2892
+ description: "Chain name (e.g. ethereum, solana, bitcoin)"
2893
+ responses:
2894
+ "200":
2895
+ description: Wallet details
2896
+ content:
2897
+ application/json:
2898
+ schema:
2899
+ $ref: "#/components/schemas/TreasuryWalletResponse"
2900
+ "401":
2901
+ $ref: "#/components/responses/Unauthorized"
2902
+ "403":
2903
+ $ref: "#/components/responses/Forbidden"
2904
+ "404":
2905
+ $ref: "#/components/responses/NotFound"
2906
+ delete:
2907
+ tags: [Treasury Wallets]
2908
+ summary: Deactivate the user's wallet for a specific chain
2909
+ operationId: deactivateTreasuryWallet
2910
+ security:
2911
+ - BearerAuth: []
2912
+ parameters:
2913
+ - name: chain
2914
+ in: path
2915
+ required: true
2916
+ schema:
2917
+ type: string
2918
+ responses:
2919
+ "204":
2920
+ description: Wallet deactivated
2921
+ "401":
2922
+ $ref: "#/components/responses/Unauthorized"
2923
+ "403":
2924
+ $ref: "#/components/responses/Forbidden"
2925
+
2926
+ /v1/treasury/wallets/{chain}/export:
2927
+ post:
2928
+ tags: [Treasury Wallets]
2929
+ summary: Export the private key for a treasury wallet
2930
+ description: |
2931
+ Returns the raw private key hex for the user's active wallet on
2932
+ the given chain. Audit-logged as `treasury_wallet.export`.
2933
+ Human users only.
2934
+ operationId: exportTreasuryWallet
2935
+ security:
2936
+ - BearerAuth: []
2937
+ parameters:
2938
+ - name: chain
2939
+ in: path
2940
+ required: true
2941
+ schema:
2942
+ type: string
2943
+ responses:
2944
+ "200":
2945
+ description: Private key exported
2946
+ content:
2947
+ application/json:
2948
+ schema:
2949
+ $ref: "#/components/schemas/TreasuryWalletExportResponse"
2950
+ "401":
2951
+ $ref: "#/components/responses/Unauthorized"
2952
+ "403":
2953
+ $ref: "#/components/responses/Forbidden"
2954
+ "404":
2955
+ $ref: "#/components/responses/NotFound"
2956
+
2957
+ /v1/treasury/wallets/{chain}/rotate:
2958
+ post:
2959
+ tags: [Treasury Wallets]
2960
+ summary: Rotate the user's wallet key for a chain
2961
+ description: |
2962
+ Generates a new keypair, deactivates the old wallet, and creates a
2963
+ new active wallet. The old private key version is retained in the
2964
+ vault for audit. Requires Pro or higher.
2965
+ operationId: rotateTreasuryWallet
2966
+ security:
2967
+ - BearerAuth: []
2968
+ parameters:
2969
+ - name: chain
2970
+ in: path
2971
+ required: true
2972
+ schema:
2973
+ type: string
2974
+ responses:
2975
+ "200":
2976
+ description: Wallet rotated
2977
+ content:
2978
+ application/json:
2979
+ schema:
2980
+ $ref: "#/components/schemas/TreasuryWalletResponse"
2981
+ "400":
2982
+ $ref: "#/components/responses/BadRequest"
2983
+ "401":
2984
+ $ref: "#/components/responses/Unauthorized"
2985
+ "403":
2986
+ $ref: "#/components/responses/Forbidden"
2987
+ "404":
2988
+ $ref: "#/components/responses/NotFound"
2989
+
2711
2990
  # ---------------------------------------------------------------------------
2712
2991
  # Admin
2713
2992
  # ---------------------------------------------------------------------------
@@ -3165,6 +3444,12 @@ components:
3165
3444
  application/json:
3166
3445
  schema:
3167
3446
  $ref: "#/components/schemas/PaymentRequirement"
3447
+ Conflict:
3448
+ description: Resource already exists or conflict
3449
+ content:
3450
+ application/json:
3451
+ schema:
3452
+ $ref: "#/components/schemas/ProblemDetails"
3168
3453
 
3169
3454
  schemas:
3170
3455
  ProblemDetails:
@@ -4200,6 +4485,23 @@ components:
4200
4485
  type: integer
4201
4486
  nullable: true
4202
4487
  description: Per-agent TTL override for federation tokens (60..=3600).
4488
+ signing_chains:
4489
+ type: array
4490
+ items:
4491
+ type: string
4492
+ description: Chains for which this agent has provisioned signing keys.
4493
+ eip712_domain_allowlist:
4494
+ type: array
4495
+ items:
4496
+ type: object
4497
+ description: JSON array of allowed EIP-712 domain entries.
4498
+ eip712_default_policy:
4499
+ type: string
4500
+ enum: [deny, allow]
4501
+ description: Default EIP-712 policy (deny blocks all unless allowlisted).
4502
+ message_signing_enabled:
4503
+ type: boolean
4504
+ description: Whether EIP-191 personal_sign is enabled.
4203
4505
  created_at:
4204
4506
  type: string
4205
4507
  format: date-time
@@ -4821,6 +5123,133 @@ components:
4821
5123
  items:
4822
5124
  $ref: "#/components/schemas/SimulateTransactionRequest"
4823
5125
 
5126
+ # Signing Keys (Multi-Chain)
5127
+ CreateSigningKeyRequest:
5128
+ type: object
5129
+ required: [chain]
5130
+ properties:
5131
+ chain:
5132
+ type: string
5133
+ enum: [ethereum, bitcoin, solana, xrp, cardano, tron]
5134
+
5135
+ SigningKeyResponse:
5136
+ type: object
5137
+ properties:
5138
+ id:
5139
+ type: string
5140
+ format: uuid
5141
+ agent_id:
5142
+ type: string
5143
+ format: uuid
5144
+ chain:
5145
+ type: string
5146
+ curve:
5147
+ type: string
5148
+ public_key:
5149
+ type: string
5150
+ address:
5151
+ type: string
5152
+ nullable: true
5153
+ key_version:
5154
+ type: integer
5155
+ is_active:
5156
+ type: boolean
5157
+ created_at:
5158
+ type: string
5159
+ format: date-time
5160
+ rotated_at:
5161
+ type: string
5162
+ format: date-time
5163
+ nullable: true
5164
+
5165
+ SigningKeyListResponse:
5166
+ type: object
5167
+ properties:
5168
+ keys:
5169
+ type: array
5170
+ items:
5171
+ $ref: "#/components/schemas/SigningKeyResponse"
5172
+
5173
+ # Unified Signing Intent
5174
+ SignIntentRequest:
5175
+ type: object
5176
+ required: [intent_type, chain]
5177
+ properties:
5178
+ intent_type:
5179
+ type: string
5180
+ enum: [personal_sign, typed_data, transaction]
5181
+ chain:
5182
+ type: string
5183
+ signing_key_path:
5184
+ type: string
5185
+ message:
5186
+ type: string
5187
+ description: Hex-encoded message bytes (for personal_sign)
5188
+ typed_data:
5189
+ type: object
5190
+ description: EIP-712 typed data JSON (for typed_data)
5191
+ tx_type:
5192
+ type: integer
5193
+ description: "EIP-2718 type: 0=legacy, 1=2930, 2=1559, 3=4844, 4=7702"
5194
+ to:
5195
+ type: string
5196
+ value:
5197
+ type: string
5198
+ data:
5199
+ type: string
5200
+ nonce:
5201
+ type: integer
5202
+ gas_limit:
5203
+ type: integer
5204
+ gas_price:
5205
+ type: string
5206
+ max_fee_per_gas:
5207
+ type: string
5208
+ max_priority_fee_per_gas:
5209
+ type: string
5210
+ access_list:
5211
+ type: array
5212
+ items:
5213
+ type: object
5214
+ max_fee_per_blob_gas:
5215
+ type: string
5216
+ blob_versioned_hashes:
5217
+ type: array
5218
+ items:
5219
+ type: string
5220
+ authorization_list:
5221
+ type: array
5222
+ items:
5223
+ type: object
5224
+
5225
+ SignIntentResponse:
5226
+ type: object
5227
+ properties:
5228
+ intent_type:
5229
+ type: string
5230
+ chain:
5231
+ type: string
5232
+ from:
5233
+ type: string
5234
+ signature:
5235
+ type: string
5236
+ nullable: true
5237
+ signed_tx:
5238
+ type: string
5239
+ nullable: true
5240
+ tx_hash:
5241
+ type: string
5242
+ nullable: true
5243
+ message_hash:
5244
+ type: string
5245
+ nullable: true
5246
+ typed_data_hash:
5247
+ type: string
5248
+ nullable: true
5249
+ tx_type:
5250
+ type: integer
5251
+ nullable: true
5252
+
4824
5253
  TransactionResponse:
4825
5254
  type: object
4826
5255
  properties:
@@ -5787,6 +6216,57 @@ components:
5787
6216
  type: string
5788
6217
  format: date-time
5789
6218
 
6219
+ # --- Treasury Wallets ---
6220
+
6221
+ GenerateTreasuryWalletsRequest:
6222
+ type: object
6223
+ properties:
6224
+ chains:
6225
+ type: array
6226
+ items:
6227
+ type: string
6228
+ description: "Chains to generate wallets for (e.g. [\"ethereum\", \"solana\"]). Omit for all supported chains."
6229
+
6230
+ TreasuryWalletResponse:
6231
+ type: object
6232
+ properties:
6233
+ id:
6234
+ type: string
6235
+ format: uuid
6236
+ chain:
6237
+ type: string
6238
+ curve:
6239
+ type: string
6240
+ description: "Cryptographic curve (e.g. secp256k1, ed25519)"
6241
+ public_key_hex:
6242
+ type: string
6243
+ address:
6244
+ type: string
6245
+ is_active:
6246
+ type: boolean
6247
+ created_at:
6248
+ type: string
6249
+ format: date-time
6250
+
6251
+ TreasuryWalletListResponse:
6252
+ type: object
6253
+ properties:
6254
+ wallets:
6255
+ type: array
6256
+ items:
6257
+ $ref: "#/components/schemas/TreasuryWalletResponse"
6258
+
6259
+ TreasuryWalletExportResponse:
6260
+ type: object
6261
+ properties:
6262
+ chain:
6263
+ type: string
6264
+ address:
6265
+ type: string
6266
+ private_key_hex:
6267
+ type: string
6268
+ description: Raw private key in hex encoding. Handle with extreme care.
6269
+
5790
6270
  # --- x402 ---
5791
6271
 
5792
6272
  PaymentRequirement:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@1claw/openapi-spec",
3
- "version": "0.20.2",
3
+ "version": "0.22.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": {