@1claw/openapi-spec 0.54.0 → 0.56.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 (4) hide show
  1. package/README.md +7 -1
  2. package/openapi.json +15156 -13617
  3. package/openapi.yaml +1070 -46
  4. package/package.json +1 -1
package/openapi.yaml CHANGED
@@ -2,7 +2,7 @@ openapi: 3.1.0
2
2
 
3
3
  info:
4
4
  title: 1Claw API
5
- version: 0.53.4
5
+ version: 0.56.3
6
6
  description: |
7
7
  Secure secret management for AI agents. Provides vaults, secrets,
8
8
  policy-based access control, agent identity, Intents API,
@@ -963,6 +963,43 @@ paths:
963
963
  "403":
964
964
  $ref: "#/components/responses/Forbidden"
965
965
 
966
+ /v1/auth/human-factor-auth:
967
+ get:
968
+ tags: [Authentication]
969
+ summary: Get effective human factor auth policy
970
+ description: |
971
+ Returns the resolved HFA policy for treasury wallet send, swap, and export.
972
+ Precedence: user override → spend policy → platform defaults.
973
+ operationId: getHumanFactorAuth
974
+ responses:
975
+ "200":
976
+ description: Effective HFA policy
977
+ content:
978
+ application/json:
979
+ schema:
980
+ $ref: "#/components/schemas/HumanFactorAuthResponse"
981
+ "403":
982
+ $ref: "#/components/responses/Forbidden"
983
+ put:
984
+ tags: [Authentication]
985
+ summary: Set user human factor auth policy
986
+ operationId: upsertHumanFactorAuth
987
+ requestBody:
988
+ required: true
989
+ content:
990
+ application/json:
991
+ schema:
992
+ $ref: "#/components/schemas/UpsertHumanFactorAuthRequest"
993
+ responses:
994
+ "200":
995
+ description: Updated policy
996
+ content:
997
+ application/json:
998
+ schema:
999
+ $ref: "#/components/schemas/HumanFactorAuthResponse"
1000
+ "403":
1001
+ $ref: "#/components/responses/Forbidden"
1002
+
966
1003
  # MFA
967
1004
 
968
1005
  /v1/auth/mfa/status:
@@ -2331,6 +2368,16 @@ paths:
2331
2368
  application/json:
2332
2369
  schema:
2333
2370
  $ref: "#/components/schemas/AgentResponse"
2371
+ "202":
2372
+ description: |
2373
+ Guardrail widening queued for human approval. The change is not
2374
+ applied until approved via POST /v1/approvals/{approval_id}/decide.
2375
+ Resubmit this PATCH with `approval_id` set to the returned value
2376
+ after approval to apply the widening.
2377
+ content:
2378
+ application/json:
2379
+ schema:
2380
+ $ref: "#/components/schemas/GuardrailWideningQueuedResponse"
2334
2381
  "404":
2335
2382
  $ref: "#/components/responses/NotFound"
2336
2383
  delete:
@@ -2904,6 +2951,276 @@ paths:
2904
2951
  # Agent Delegations
2905
2952
  # ---------------------------------------------------------------------------
2906
2953
 
2954
+ /v1/agents/{agent_id}/accounts:
2955
+ get:
2956
+ tags: [Agents]
2957
+ summary: List agent on-chain accounts
2958
+ operationId: listAgentAccounts
2959
+ parameters:
2960
+ - $ref: "#/components/parameters/AgentId"
2961
+ responses:
2962
+ "200":
2963
+ description: Agent accounts
2964
+ content:
2965
+ application/json:
2966
+ schema:
2967
+ $ref: "#/components/schemas/AgentAccountListResponse"
2968
+ "401":
2969
+ $ref: "#/components/responses/Unauthorized"
2970
+ "403":
2971
+ $ref: "#/components/responses/Forbidden"
2972
+ "404":
2973
+ $ref: "#/components/responses/NotFound"
2974
+ post:
2975
+ tags: [Agents]
2976
+ summary: Provision an agent account record
2977
+ description: Human-only. Creates a DB record for an EOA or Safe account (Safe onchain sync is stubbed).
2978
+ operationId: provisionAgentAccount
2979
+ parameters:
2980
+ - $ref: "#/components/parameters/AgentId"
2981
+ requestBody:
2982
+ required: true
2983
+ content:
2984
+ application/json:
2985
+ schema:
2986
+ $ref: "#/components/schemas/ProvisionAgentAccountRequest"
2987
+ responses:
2988
+ "201":
2989
+ description: Account provisioned
2990
+ content:
2991
+ application/json:
2992
+ schema:
2993
+ $ref: "#/components/schemas/AgentAccountResponse"
2994
+ "401":
2995
+ $ref: "#/components/responses/Unauthorized"
2996
+ "403":
2997
+ $ref: "#/components/responses/Forbidden"
2998
+ "404":
2999
+ $ref: "#/components/responses/NotFound"
3000
+
3001
+ /v1/agents/{agent_id}/accounts/migrate:
3002
+ post:
3003
+ tags: [Agents]
3004
+ summary: EOA to Safe migration wizard
3005
+ description: Human-only. Provisions counterfactual Safe and returns sweep plan. Onchain module broadcast stubbed pre-audit.
3006
+ operationId: migrateAgentToSafe
3007
+ parameters:
3008
+ - $ref: "#/components/parameters/AgentId"
3009
+ requestBody:
3010
+ required: true
3011
+ content:
3012
+ application/json:
3013
+ schema:
3014
+ type: object
3015
+ required: [chain]
3016
+ properties:
3017
+ chain:
3018
+ type: string
3019
+ deprecate_eoa:
3020
+ type: boolean
3021
+ responses:
3022
+ "200":
3023
+ description: Migration plan
3024
+ content:
3025
+ application/json:
3026
+ schema:
3027
+ $ref: "#/components/schemas/MigrationPlanResponse"
3028
+ "401":
3029
+ $ref: "#/components/responses/Unauthorized"
3030
+ "403":
3031
+ $ref: "#/components/responses/Forbidden"
3032
+ "404":
3033
+ $ref: "#/components/responses/NotFound"
3034
+
3035
+ /v1/agents/{agent_id}/accounts/{chain}/deprecate-eoa:
3036
+ post:
3037
+ tags: [Agents]
3038
+ summary: Mark agent EOA account deprecated
3039
+ operationId: deprecateAgentEoa
3040
+ parameters:
3041
+ - $ref: "#/components/parameters/AgentId"
3042
+ - name: chain
3043
+ in: path
3044
+ required: true
3045
+ schema:
3046
+ type: string
3047
+ responses:
3048
+ "200":
3049
+ description: Updated account
3050
+ content:
3051
+ application/json:
3052
+ schema:
3053
+ $ref: "#/components/schemas/AgentAccountResponse"
3054
+ "401":
3055
+ $ref: "#/components/responses/Unauthorized"
3056
+ "403":
3057
+ $ref: "#/components/responses/Forbidden"
3058
+ "404":
3059
+ $ref: "#/components/responses/NotFound"
3060
+
3061
+ /v1/agents/{agent_id}/accounts/{chain}/deploy:
3062
+ post:
3063
+ tags: [Agents]
3064
+ summary: Lazy-deploy counterfactual Safe (stub)
3065
+ description: Human-only. Broadcasts Safe deployment when Guard audit completes. Returns 501 pre-audit.
3066
+ operationId: deployAgentSafeAccount
3067
+ parameters:
3068
+ - $ref: "#/components/parameters/AgentId"
3069
+ - name: chain
3070
+ in: path
3071
+ required: true
3072
+ schema:
3073
+ type: string
3074
+ responses:
3075
+ "501":
3076
+ description: Not implemented (Phase 5.1)
3077
+ content:
3078
+ application/json:
3079
+ schema:
3080
+ $ref: "#/components/schemas/NotImplementedResponse"
3081
+ "401":
3082
+ $ref: "#/components/responses/Unauthorized"
3083
+ "403":
3084
+ $ref: "#/components/responses/Forbidden"
3085
+ "404":
3086
+ $ref: "#/components/responses/NotFound"
3087
+
3088
+ /v1/org/safe/sync-allowances:
3089
+ post:
3090
+ tags: [Organization]
3091
+ summary: Reconcile Safe allowance targets (org admin)
3092
+ description: Compiles tx_daily_limit targets for Safe agents. Onchain read/write stubbed pre-audit.
3093
+ operationId: syncOrgSafeAllowances
3094
+ responses:
3095
+ "200":
3096
+ description: Reconciliation report
3097
+ content:
3098
+ application/json:
3099
+ schema:
3100
+ $ref: "#/components/schemas/AllowanceReconcileReport"
3101
+ "401":
3102
+ $ref: "#/components/responses/Unauthorized"
3103
+ "403":
3104
+ $ref: "#/components/responses/Forbidden"
3105
+
3106
+ /v1/treasury/{treasury_id}/safe/roles-sync:
3107
+ post:
3108
+ tags: [Treasury]
3109
+ summary: Sync treasury Safe Roles module (stub)
3110
+ description: Human-only. Reconciles on-chain Roles config with agent guardrails. Returns 501 pre-audit.
3111
+ operationId: treasurySafeRolesSync
3112
+ parameters:
3113
+ - name: treasury_id
3114
+ in: path
3115
+ required: true
3116
+ schema:
3117
+ type: string
3118
+ format: uuid
3119
+ responses:
3120
+ "501":
3121
+ description: Not implemented (Phase 5.9)
3122
+ content:
3123
+ application/json:
3124
+ schema:
3125
+ $ref: "#/components/schemas/NotImplementedResponse"
3126
+ "401":
3127
+ $ref: "#/components/responses/Unauthorized"
3128
+ "403":
3129
+ $ref: "#/components/responses/Forbidden"
3130
+ "404":
3131
+ $ref: "#/components/responses/NotFound"
3132
+
3133
+ /v1/agents/{agent_id}/safe/cosign:
3134
+ post:
3135
+ tags: [Agents]
3136
+ summary: Enable Vault co-signer (stub)
3137
+ operationId: enableSafeCosign
3138
+ parameters:
3139
+ - $ref: "#/components/parameters/AgentId"
3140
+ responses:
3141
+ "501":
3142
+ description: Not implemented (Phase 5.2)
3143
+
3144
+ /v1/agents/{agent_id}/safe/passkey-enroll:
3145
+ post:
3146
+ tags: [Agents]
3147
+ summary: Enroll passkey Safe owner (stub)
3148
+ operationId: enrollSafePasskeyOwner
3149
+ parameters:
3150
+ - $ref: "#/components/parameters/AgentId"
3151
+ responses:
3152
+ "501":
3153
+ description: Not implemented (Phase 5.5)
3154
+
3155
+ /v1/agents/{agent_id}/safe/timelock:
3156
+ post:
3157
+ tags: [Agents]
3158
+ summary: Configure Zodiac timelock (stub)
3159
+ operationId: configureSafeTimelock
3160
+ parameters:
3161
+ - $ref: "#/components/parameters/AgentId"
3162
+ responses:
3163
+ "501":
3164
+ description: Not implemented (Phase 5.6)
3165
+
3166
+ /v1/agents/{agent_id}/safe/erc4337:
3167
+ post:
3168
+ tags: [Agents]
3169
+ summary: Enable ERC-4337 Safe lane (stub)
3170
+ operationId: enableSafeErc4337
3171
+ parameters:
3172
+ - $ref: "#/components/parameters/AgentId"
3173
+ responses:
3174
+ "501":
3175
+ description: Not implemented (Phase 5.8)
3176
+
3177
+ /v1/agents/{agent_id}/guardrails/replay:
3178
+ post:
3179
+ tags: [Agents]
3180
+ summary: Dry-run guardrail changes against recent transactions
3181
+ description: Human-only. Compares draft guardrails against recent agent transactions.
3182
+ operationId: replayAgentGuardrails
3183
+ parameters:
3184
+ - $ref: "#/components/parameters/AgentId"
3185
+ requestBody:
3186
+ content:
3187
+ application/json:
3188
+ schema:
3189
+ $ref: "#/components/schemas/GuardrailReplayRequest"
3190
+ responses:
3191
+ "200":
3192
+ description: Replay report
3193
+ content:
3194
+ application/json:
3195
+ schema:
3196
+ $ref: "#/components/schemas/GuardrailReplayResponse"
3197
+ "401":
3198
+ $ref: "#/components/responses/Unauthorized"
3199
+ "403":
3200
+ $ref: "#/components/responses/Forbidden"
3201
+ "404":
3202
+ $ref: "#/components/responses/NotFound"
3203
+
3204
+ /v1/safe/module-registry/{chain}:
3205
+ get:
3206
+ tags: [Agents]
3207
+ summary: List Safe module registry entries for a chain
3208
+ operationId: getSafeModuleRegistry
3209
+ security: []
3210
+ parameters:
3211
+ - name: chain
3212
+ in: path
3213
+ required: true
3214
+ schema:
3215
+ type: string
3216
+ responses:
3217
+ "200":
3218
+ description: Module registry
3219
+ content:
3220
+ application/json:
3221
+ schema:
3222
+ $ref: "#/components/schemas/SafeModuleRegistryResponse"
3223
+
2907
3224
  /v1/agents/{agent_id}/delegations:
2908
3225
  post:
2909
3226
  tags: [Delegations]
@@ -3174,6 +3491,15 @@ paths:
3174
3491
  application/json:
3175
3492
  schema:
3176
3493
  $ref: "#/components/schemas/BindingResponse"
3494
+ "202":
3495
+ description: |
3496
+ Binding guardrail widening queued for human approval. Resubmit
3497
+ PATCH with `approval_id` after approval via
3498
+ POST /v1/approvals/{approval_id}/decide.
3499
+ content:
3500
+ application/json:
3501
+ schema:
3502
+ $ref: "#/components/schemas/GuardrailWideningQueuedResponse"
3177
3503
  "400":
3178
3504
  $ref: "#/components/responses/BadRequest"
3179
3505
  "404":
@@ -3636,29 +3962,103 @@ paths:
3636
3962
  "404":
3637
3963
  description: Agent-keys vault not found
3638
3964
 
3639
- /v1/org/bankr-config:
3965
+ /v1/org/status:
3640
3966
  get:
3641
3967
  tags: [Organization]
3642
- summary: Get org Bankr partner configuration
3643
- description: Returns whether the org has configured Bankr BYOK (partner key prefix and default wallet only — never the secret). Users only.
3644
- operationId: getOrgBankrConfig
3968
+ summary: Organization operational status
3969
+ description: Returns whether the org is emergency-frozen (blocks agent tx/execution).
3970
+ operationId: getOrgStatus
3645
3971
  responses:
3646
3972
  "200":
3647
- description: Bankr configuration status
3973
+ description: Current org status
3648
3974
  content:
3649
3975
  application/json:
3650
3976
  schema:
3651
- $ref: "#/components/schemas/OrgBankrConfigResponse"
3652
- put:
3977
+ type: object
3978
+ required: [org_id, status]
3979
+ properties:
3980
+ org_id:
3981
+ type: string
3982
+ format: uuid
3983
+ status:
3984
+ type: string
3985
+ enum: [active, frozen]
3986
+ frozen_at:
3987
+ type: string
3988
+ format: date-time
3989
+ nullable: true
3990
+ "403":
3991
+ description: Forbidden
3992
+
3993
+ /v1/org/freeze:
3994
+ post:
3653
3995
  tags: [Organization]
3654
- summary: Set org Bankr partner configuration
3655
- description: Store or replace the org's Bankr partner key (`bk_ptr_...`) and optional default wallet (`wlt_...`). Owner/admin only. Partner key encrypted at rest.
3656
- operationId: upsertOrgBankrConfig
3657
- requestBody:
3658
- required: true
3659
- content:
3660
- application/json:
3661
- schema:
3996
+ summary: Emergency org-wide freeze
3997
+ description: Sets organizations.frozen_at — blocks agent tx/execution until unfreeze. Owner/admin only.
3998
+ operationId: freezeOrg
3999
+ responses:
4000
+ "200":
4001
+ description: Organization frozen
4002
+ content:
4003
+ application/json:
4004
+ schema:
4005
+ type: object
4006
+ properties:
4007
+ status:
4008
+ type: string
4009
+ enum: [frozen]
4010
+ org_id:
4011
+ type: string
4012
+ format: uuid
4013
+ "403":
4014
+ description: Forbidden
4015
+
4016
+ /v1/org/unfreeze:
4017
+ post:
4018
+ tags: [Organization]
4019
+ summary: Clear org-wide freeze
4020
+ description: Clears organizations.frozen_at. Owner/admin only.
4021
+ operationId: unfreezeOrg
4022
+ responses:
4023
+ "200":
4024
+ description: Organization unfrozen
4025
+ content:
4026
+ application/json:
4027
+ schema:
4028
+ type: object
4029
+ properties:
4030
+ status:
4031
+ type: string
4032
+ enum: [unfrozen]
4033
+ org_id:
4034
+ type: string
4035
+ format: uuid
4036
+ "403":
4037
+ description: Forbidden
4038
+
4039
+ /v1/org/bankr-config:
4040
+ get:
4041
+ tags: [Organization]
4042
+ summary: Get org Bankr partner configuration
4043
+ description: Returns whether the org has configured Bankr BYOK (partner key prefix and default wallet only — never the secret). Users only.
4044
+ operationId: getOrgBankrConfig
4045
+ responses:
4046
+ "200":
4047
+ description: Bankr configuration status
4048
+ content:
4049
+ application/json:
4050
+ schema:
4051
+ $ref: "#/components/schemas/OrgBankrConfigResponse"
4052
+ put:
4053
+ tags: [Organization]
4054
+ summary: Set org Bankr partner configuration
4055
+ description: Store or replace the org's Bankr partner key (`bk_ptr_...`) and optional default wallet (`wlt_...`). Owner/admin only. Partner key encrypted at rest.
4056
+ operationId: upsertOrgBankrConfig
4057
+ requestBody:
4058
+ required: true
4059
+ content:
4060
+ application/json:
4061
+ schema:
3662
4062
  $ref: "#/components/schemas/UpsertOrgBankrConfigRequest"
3663
4063
  responses:
3664
4064
  "200":
@@ -5075,6 +5475,29 @@ paths:
5075
5475
  "403":
5076
5476
  $ref: "#/components/responses/Forbidden"
5077
5477
 
5478
+ /v1/treasury/wallets/auth-policy:
5479
+ get:
5480
+ tags: [Treasury Wallets]
5481
+ summary: Get effective human factor auth policy for embedded clients
5482
+ description: |
5483
+ Returns the resolved human factor auth (HFA) policy governing treasury
5484
+ wallet send, swap, and export, plus the number of passkeys registered
5485
+ for the calling user. Intended for embedded wallet clients; equivalent
5486
+ to GET /v1/auth/human-factor-auth with an additional passkey count.
5487
+ Precedence: user override → platform app → spend policy → defaults.
5488
+ operationId: getTreasuryAuthPolicy
5489
+ security:
5490
+ - BearerAuth: []
5491
+ responses:
5492
+ "200":
5493
+ description: Effective HFA policy with passkey registration count
5494
+ content:
5495
+ application/json:
5496
+ schema:
5497
+ $ref: "#/components/schemas/TreasuryAuthPolicyResponse"
5498
+ "403":
5499
+ $ref: "#/components/responses/Forbidden"
5500
+
5078
5501
  /v1/treasury/wallets/spend-policy:
5079
5502
  get:
5080
5503
  tags: [Treasury Wallets]
@@ -6899,9 +7322,10 @@ paths:
6899
7322
  tags: [Authentication]
6900
7323
  summary: Begin passkey transaction authorization
6901
7324
  description: |
6902
- Requires `tx_digest` — SHA-256 hex of canonical `chain|to|value_wei|data`
6903
- for the treasury send being authorized. The server recomputes this digest
6904
- on send and rejects passkey tokens that do not match.
7325
+ Requires `tx_digest` — SHA-256 hex of the canonical digest for the
7326
+ treasury action being authorized (`send` or `swap`). The server
7327
+ recomputes this digest on send/swap and rejects passkey tokens that
7328
+ do not match.
6905
7329
  operationId: passkeyTxAssertBegin
6906
7330
  security:
6907
7331
  - BearerAuth: []
@@ -6910,17 +7334,20 @@ paths:
6910
7334
  content:
6911
7335
  application/json:
6912
7336
  schema:
6913
- type: object
6914
- required: [tx_digest]
6915
- properties:
6916
- tx_digest:
6917
- type: string
6918
- description: 64-char hex SHA-256 of canonical send params
7337
+ $ref: "#/components/schemas/PasskeyTxAssertBeginRequest"
6919
7338
  responses:
6920
7339
  "200":
6921
7340
  description: WebAuthn challenge
7341
+ content:
7342
+ application/json:
7343
+ schema:
7344
+ $ref: "#/components/schemas/PasskeyAssertBeginResponse"
6922
7345
  "400":
6923
- description: Missing or invalid tx_digest
7346
+ description: Missing or invalid tx_digest, or invalid action
7347
+ "403":
7348
+ $ref: "#/components/responses/Forbidden"
7349
+ "404":
7350
+ description: No passkeys registered for the user
6924
7351
 
6925
7352
  /v1/auth/passkeys/tx-assert/complete:
6926
7353
  post:
@@ -9685,6 +10112,59 @@ paths:
9685
10112
  "403":
9686
10113
  $ref: "#/components/responses/Forbidden"
9687
10114
 
10115
+ /v1/org/guardrail-shadow-report:
10116
+ get:
10117
+ tags: [Organization]
10118
+ summary: Get guardrail shadow divergence report
10119
+ description: |
10120
+ Returns Convention 6 shadow-mode violations (`guardrail_shadow.would_deny` audit events)
10121
+ grouped by reason code. Owner/admin only.
10122
+ operationId: getGuardrailShadowReport
10123
+ security:
10124
+ - BearerAuth: []
10125
+ parameters:
10126
+ - name: since
10127
+ in: query
10128
+ schema:
10129
+ type: string
10130
+ format: date-time
10131
+ - name: until
10132
+ in: query
10133
+ schema:
10134
+ type: string
10135
+ format: date-time
10136
+ responses:
10137
+ "200":
10138
+ description: Guardrail shadow report
10139
+ content:
10140
+ application/json:
10141
+ schema:
10142
+ $ref: "#/components/schemas/GuardrailShadowReportResponse"
10143
+ "401":
10144
+ $ref: "#/components/responses/Unauthorized"
10145
+ "403":
10146
+ $ref: "#/components/responses/Forbidden"
10147
+
10148
+ /v1/org/guardrail-revisions:
10149
+ get:
10150
+ tags: [Organization]
10151
+ summary: List guardrail revision history
10152
+ description: Audit trail of agent and binding guardrail changes. Owner/admin only.
10153
+ operationId: listGuardrailRevisions
10154
+ security:
10155
+ - BearerAuth: []
10156
+ responses:
10157
+ "200":
10158
+ description: Guardrail revisions
10159
+ content:
10160
+ application/json:
10161
+ schema:
10162
+ $ref: "#/components/schemas/GuardrailRevisionListResponse"
10163
+ "401":
10164
+ $ref: "#/components/responses/Unauthorized"
10165
+ "403":
10166
+ $ref: "#/components/responses/Forbidden"
10167
+
9688
10168
  # ---------------------------------------------------------------------------
9689
10169
  # Contract ABI Registry
9690
10170
  # ---------------------------------------------------------------------------
@@ -11970,7 +12450,9 @@ components:
11970
12450
  additionalProperties: true
11971
12451
  description: |
11972
12452
  Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron).
11973
- Each value may include max_value, daily_limit, to_allowlist, token_allowlist, max_per_day, overhead_budget, max_ata_creates_per_day.
12453
+ Each value may include max_value, daily_limit, to_allowlist, token_allowlist, max_per_day,
12454
+ overhead_budget, max_ata_creates_per_day, max_fee_per_gas_gwei, max_gas_limit,
12455
+ gas_daily_budget_native (UTC-day cumulative EVM gas estimate in native units).
11974
12456
  Strictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.
11975
12457
  tx_max_per_day:
11976
12458
  type: integer
@@ -12021,6 +12503,47 @@ components:
12021
12503
  type: string
12022
12504
  enum: [deny, approve]
12023
12505
  description: Simulation failure escalation — deny (422) or route to HITL (approve).
12506
+ tx_block_unlimited_approvals:
12507
+ type: boolean
12508
+ default: false
12509
+ description: Block unlimited ERC-20 approvals (max uint256 / setApprovalForAll).
12510
+ tx_per_recipient_max_per_day:
12511
+ type: integer
12512
+ nullable: true
12513
+ description: Max transactions to the same recipient address per UTC day.
12514
+ tx_per_recipient_daily_limit:
12515
+ type: string
12516
+ nullable: true
12517
+ description: Max native-unit spend to the same recipient per UTC day.
12518
+ new_recipient_cap_native:
12519
+ type: string
12520
+ nullable: true
12521
+ description: Cap on first-time recipient spend in native units.
12522
+ tx_max_value_usd:
12523
+ type: string
12524
+ nullable: true
12525
+ description: Per-transaction USD cap (requires price oracle).
12526
+ tx_daily_limit_usd:
12527
+ type: string
12528
+ nullable: true
12529
+ description: Rolling 24h USD spend cap (requires price oracle).
12530
+ raw_signing_policy:
12531
+ type: string
12532
+ enum: [allow, deny, approve]
12533
+ default: allow
12534
+ description: Raw digest signing policy — allow, deny, or route to HITL (approve).
12535
+ personal_sign_policy:
12536
+ type: object
12537
+ additionalProperties: true
12538
+ description: personal_sign guardrails (message allowlist, max bytes, etc.).
12539
+ allow_erc4337:
12540
+ type: boolean
12541
+ default: false
12542
+ description: Allow ERC-4337 gasless UserOperations.
12543
+ allow_eip7702:
12544
+ type: boolean
12545
+ default: false
12546
+ description: Allow EIP-7702 (tx type 4) set-code transactions.
12024
12547
  api_key_expires_at:
12025
12548
  type: string
12026
12549
  format: date-time
@@ -12160,6 +12683,43 @@ components:
12160
12683
  enum: [deny, approve]
12161
12684
  nullable: true
12162
12685
  description: Simulation failure escalation policy.
12686
+ tx_block_unlimited_approvals:
12687
+ type: boolean
12688
+ description: Block unlimited ERC-20 approvals (max uint256 / setApprovalForAll).
12689
+ tx_per_recipient_max_per_day:
12690
+ type: integer
12691
+ nullable: true
12692
+ description: Max transactions to the same recipient per UTC day. Null clears.
12693
+ tx_per_recipient_daily_limit:
12694
+ type: string
12695
+ nullable: true
12696
+ description: Max native spend to same recipient per UTC day. Null clears.
12697
+ new_recipient_cap_native:
12698
+ type: string
12699
+ nullable: true
12700
+ description: First-time recipient native cap. Null clears.
12701
+ tx_max_value_usd:
12702
+ type: string
12703
+ nullable: true
12704
+ description: Per-tx USD cap. Null clears.
12705
+ tx_daily_limit_usd:
12706
+ type: string
12707
+ nullable: true
12708
+ description: Rolling 24h USD spend cap. Null clears.
12709
+ raw_signing_policy:
12710
+ type: string
12711
+ enum: [allow, deny, approve]
12712
+ description: Raw digest signing policy.
12713
+ personal_sign_policy:
12714
+ type: object
12715
+ additionalProperties: true
12716
+ description: personal_sign guardrails JSON.
12717
+ allow_erc4337:
12718
+ type: boolean
12719
+ description: Allow ERC-4337 gasless UserOperations.
12720
+ allow_eip7702:
12721
+ type: boolean
12722
+ description: Allow EIP-7702 (tx type 4).
12163
12723
  clear_auto_suspended:
12164
12724
  type: boolean
12165
12725
  description: When true, clears circuit-breaker auto-suspension (human owner/admin only).
@@ -12206,7 +12766,8 @@ components:
12206
12766
  additionalProperties: true
12207
12767
  description: |
12208
12768
  Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron).
12209
- Each value may include max_value, daily_limit, to_allowlist, token_allowlist (legacy *_eth keys accepted).
12769
+ Each value may include max_value, daily_limit, to_allowlist, token_allowlist (legacy *_eth keys accepted),
12770
+ max_fee_per_gas_gwei, max_gas_limit, gas_daily_budget_native (UTC-day cumulative EVM gas in native units).
12210
12771
  Strictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.
12211
12772
  api_key_expires_at:
12212
12773
  type: string
@@ -12227,6 +12788,17 @@ components:
12227
12788
  type: object
12228
12789
  additionalProperties: true
12229
12790
  description: Per-environment guardrail overrides keyed by environment slug.
12791
+ address_screening_policy:
12792
+ type: object
12793
+ additionalProperties: true
12794
+ description: Recipient address screening policy. `mode` may be `off`, `deny`, or `approve`.
12795
+ approval_id:
12796
+ type: string
12797
+ format: uuid
12798
+ description: >
12799
+ Approved policy_change id when applying a queued guardrail
12800
+ widening. Resubmit PATCH with this field after the approval
12801
+ has been approved via POST /v1/approvals/{approval_id}/decide.
12230
12802
 
12231
12803
  AgentResponse:
12232
12804
  type: object
@@ -12377,6 +12949,35 @@ components:
12377
12949
  type: string
12378
12950
  enum: [deny, approve]
12379
12951
  nullable: true
12952
+ tx_block_unlimited_approvals:
12953
+ type: boolean
12954
+ description: Block unlimited ERC-20 approvals.
12955
+ tx_per_recipient_max_per_day:
12956
+ type: integer
12957
+ nullable: true
12958
+ tx_per_recipient_daily_limit:
12959
+ type: string
12960
+ nullable: true
12961
+ new_recipient_cap_native:
12962
+ type: string
12963
+ nullable: true
12964
+ tx_max_value_usd:
12965
+ type: string
12966
+ nullable: true
12967
+ tx_daily_limit_usd:
12968
+ type: string
12969
+ nullable: true
12970
+ raw_signing_policy:
12971
+ type: string
12972
+ enum: [allow, deny, approve]
12973
+ personal_sign_policy:
12974
+ type: object
12975
+ additionalProperties: true
12976
+ nullable: true
12977
+ allow_erc4337:
12978
+ type: boolean
12979
+ allow_eip7702:
12980
+ type: boolean
12380
12981
  auto_suspended:
12381
12982
  type: boolean
12382
12983
  description: True when circuit breaker auto-suspended the agent after repeated guardrail denials.
@@ -12485,6 +13086,10 @@ components:
12485
13086
  type: object
12486
13087
  additionalProperties: true
12487
13088
  description: Per-environment guardrail overrides keyed by environment slug.
13089
+ address_screening_policy:
13090
+ type: object
13091
+ additionalProperties: true
13092
+ description: Recipient address screening policy. `mode` may be `off`, `deny`, or `approve`.
12488
13093
 
12489
13094
  KnownToken:
12490
13095
  type: object
@@ -16212,32 +16817,52 @@ components:
16212
16817
  format: date-time
16213
16818
  nullable: true
16214
16819
 
16820
+ GuardrailReasonCode:
16821
+ type: string
16822
+ description: |
16823
+ Stable snake_case reason codes for guardrail violations (Convention 1).
16824
+ Shadow-mode `"log"` emits the same codes in `guardrail_shadow.would_deny`
16825
+ audit events with `enforced: false`. 202 HITL responses use
16826
+ `approval_available: true` instead of a deny reason_code.
16827
+ enum:
16828
+ - binding_rpm_exceeded
16829
+ - agent_rpm_exceeded
16830
+ - graphql_mutation_blocked
16831
+ - graphql_depth_exceeded
16832
+ - graphql_parse_failed
16833
+ - graphql_introspection_blocked
16834
+ - response_too_large
16835
+ - request_too_large
16836
+ - method_not_allowed
16837
+ - header_not_allowed
16838
+ - dns_private_ip_blocked
16839
+ - agent_suspended
16840
+ - outside_time_window
16841
+ - secret_in_request
16842
+ - concurrency_exceeded
16843
+ - org_frozen
16844
+ - price_unavailable
16845
+ - gas_fee_exceeded
16846
+ - unlimited_approval_blocked
16847
+ - tx_per_recipient_limit_exceeded
16848
+ - tx_max_value_exceeded
16849
+ - tx_daily_limit_exceeded
16850
+ - delegation_signing_blocked
16851
+ - recipient_screening_failed
16852
+ - screening_provider_unavailable
16853
+ - human_factor_auth_required
16854
+ - register_passkey_required
16855
+
16215
16856
  GuardrailViolation:
16216
16857
  type: object
16858
+ description: Convention 1 machine-readable guardrail denial JSON body.
16217
16859
  required: [error, reason_code, approval_available]
16218
16860
  properties:
16219
16861
  error:
16220
16862
  type: string
16221
16863
  enum: [guardrail_violation]
16222
16864
  reason_code:
16223
- type: string
16224
- enum:
16225
- - binding_rpm_exceeded
16226
- - agent_rpm_exceeded
16227
- - graphql_mutation_blocked
16228
- - graphql_depth_exceeded
16229
- - graphql_parse_failed
16230
- - graphql_introspection_blocked
16231
- - response_too_large
16232
- - request_too_large
16233
- - method_not_allowed
16234
- - header_not_allowed
16235
- - dns_private_ip_blocked
16236
- - agent_suspended
16237
- - outside_time_window
16238
- - secret_in_request
16239
- - concurrency_exceeded
16240
- - org_frozen
16865
+ $ref: "#/components/schemas/GuardrailReasonCode"
16241
16866
  limit:
16242
16867
  type: string
16243
16868
  nullable: true
@@ -16257,6 +16882,11 @@ components:
16257
16882
  type: string
16258
16883
  nullable: true
16259
16884
 
16885
+ GuardrailDenial:
16886
+ description: Alias of GuardrailViolation (Convention 1 JSON shape).
16887
+ allOf:
16888
+ - $ref: "#/components/schemas/GuardrailViolation"
16889
+
16260
16890
  # --- Email OTP ---
16261
16891
 
16262
16892
  EmailOtpVerifyResponse:
@@ -16379,6 +17009,13 @@ components:
16379
17009
  max_transactions_per_day:
16380
17010
  type: integer
16381
17011
  description: Maximum number of transactions per 24h window
17012
+ human_factor_auth:
17013
+ type: object
17014
+ additionalProperties: true
17015
+ description: |
17016
+ Human factor auth requirements for send/swap/export.
17017
+ Fields: send, swap, export (password_or_passkey | passkey_only | passkey_required | password_only | reauth_token_only),
17018
+ conditional.require_passkey_above_usd, conditional.require_passkey_for_new_recipient.
16382
17019
 
16383
17020
  SpendPolicyResponse:
16384
17021
  type: object
@@ -16415,12 +17052,129 @@ components:
16415
17052
  max_transactions_per_day:
16416
17053
  type: integer
16417
17054
  nullable: true
17055
+ human_factor_auth:
17056
+ type: object
17057
+ additionalProperties: true
17058
+ nullable: true
16418
17059
  created_at:
16419
17060
  type: string
16420
17061
  format: date-time
16421
17062
 
16422
17063
  # --- Risk Engine ---
16423
17064
 
17065
+ HumanFactorAuthPolicy:
17066
+ type: object
17067
+ properties:
17068
+ send:
17069
+ type: string
17070
+ enum: [password_or_passkey, passkey_only, passkey_required, password_only, reauth_token_only]
17071
+ swap:
17072
+ type: string
17073
+ enum: [password_or_passkey, passkey_only, passkey_required, password_only, reauth_token_only]
17074
+ export:
17075
+ type: string
17076
+ enum: [password_or_passkey, passkey_only, passkey_required, password_only, reauth_token_only]
17077
+ conditional:
17078
+ type: object
17079
+ properties:
17080
+ require_passkey_above_usd:
17081
+ type: string
17082
+ nullable: true
17083
+ require_passkey_for_new_recipient:
17084
+ type: boolean
17085
+
17086
+ UpsertHumanFactorAuthRequest:
17087
+ type: object
17088
+ required: [policy]
17089
+ properties:
17090
+ policy:
17091
+ $ref: "#/components/schemas/HumanFactorAuthPolicy"
17092
+
17093
+ HumanFactorAuthResponse:
17094
+ type: object
17095
+ required: [policy, source]
17096
+ properties:
17097
+ policy:
17098
+ $ref: "#/components/schemas/HumanFactorAuthPolicy"
17099
+ source:
17100
+ type: string
17101
+ description: user | platform_app | spend_policy | default
17102
+
17103
+ TreasuryAuthPolicyResponse:
17104
+ type: object
17105
+ required: [policy, source, registered_passkeys]
17106
+ properties:
17107
+ policy:
17108
+ $ref: "#/components/schemas/HumanFactorAuthPolicy"
17109
+ source:
17110
+ type: string
17111
+ description: user | platform_app | spend_policy | default
17112
+ registered_passkeys:
17113
+ type: integer
17114
+ minimum: 0
17115
+ description: Number of WebAuthn passkeys registered for the calling user.
17116
+
17117
+ PasskeyTxAssertBeginRequest:
17118
+ type: object
17119
+ required: [tx_digest]
17120
+ properties:
17121
+ tx_digest:
17122
+ type: string
17123
+ description: 64-char hex SHA-256 of canonical send or swap params
17124
+ action:
17125
+ type: string
17126
+ enum: [send, swap]
17127
+ default: send
17128
+ description: Treasury action being authorized. Defaults to `send`.
17129
+
17130
+ PasskeyAssertBeginResponse:
17131
+ type: object
17132
+ required: [challenge, rp_id, timeout, user_verification, allow_credentials]
17133
+ properties:
17134
+ challenge:
17135
+ type: string
17136
+ rp_id:
17137
+ type: string
17138
+ timeout:
17139
+ type: integer
17140
+ user_verification:
17141
+ type: string
17142
+ allow_credentials:
17143
+ type: array
17144
+ items:
17145
+ $ref: "#/components/schemas/AllowCredential"
17146
+
17147
+ AllowCredential:
17148
+ type: object
17149
+ required: [id, type]
17150
+ properties:
17151
+ id:
17152
+ type: string
17153
+ type:
17154
+ type: string
17155
+ enum: [public-key]
17156
+ transports:
17157
+ type: array
17158
+ items:
17159
+ type: string
17160
+
17161
+ GuardrailWideningQueuedResponse:
17162
+ type: object
17163
+ required: [status, approval_id, revision_id, message]
17164
+ properties:
17165
+ status:
17166
+ type: string
17167
+ enum: [awaiting_approval]
17168
+ approval_id:
17169
+ type: string
17170
+ format: uuid
17171
+ revision_id:
17172
+ type: string
17173
+ format: uuid
17174
+ message:
17175
+ type: string
17176
+ description: Human-readable explanation of the queued change.
17177
+
16424
17178
  RiskEvent:
16425
17179
  type: object
16426
17180
  required: [id, occurred_at, principal_type, principal_id, org_id, event_type, payload, created_at]
@@ -16657,6 +17411,13 @@ components:
16657
17411
  description: "Legacy: inline credential value."
16658
17412
  credential_source:
16659
17413
  $ref: "#/components/schemas/CredentialSource"
17414
+ approval_id:
17415
+ type: string
17416
+ format: uuid
17417
+ description: >
17418
+ Approved policy_change id when applying a queued binding
17419
+ guardrail widening. Resubmit PATCH with this field after
17420
+ approval via POST /v1/approvals/{approval_id}/decide.
16660
17421
 
16661
17422
  BindingGuardrails:
16662
17423
  type: object
@@ -18372,6 +19133,269 @@ components:
18372
19133
  type: string
18373
19134
  format: date-time
18374
19135
 
19136
+ GuardrailShadowReportResponse:
19137
+ type: object
19138
+ properties:
19139
+ org_id:
19140
+ type: string
19141
+ format: uuid
19142
+ since:
19143
+ type: string
19144
+ format: date-time
19145
+ until:
19146
+ type: string
19147
+ format: date-time
19148
+ total_would_deny:
19149
+ type: integer
19150
+ format: int64
19151
+ by_reason:
19152
+ type: array
19153
+ items:
19154
+ $ref: "#/components/schemas/GuardrailShadowReasonRow"
19155
+
19156
+ GuardrailShadowReasonRow:
19157
+ type: object
19158
+ properties:
19159
+ reason_code:
19160
+ type: string
19161
+ would_deny_count:
19162
+ type: integer
19163
+ format: int64
19164
+ enforced_count:
19165
+ type: integer
19166
+ format: int64
19167
+
19168
+ GuardrailRevisionListResponse:
19169
+ type: object
19170
+ properties:
19171
+ revisions:
19172
+ type: array
19173
+ items:
19174
+ $ref: "#/components/schemas/GuardrailRevisionRow"
19175
+
19176
+ GuardrailRevisionRow:
19177
+ type: object
19178
+ properties:
19179
+ id:
19180
+ type: string
19181
+ format: uuid
19182
+ org_id:
19183
+ type: string
19184
+ format: uuid
19185
+ resource_type:
19186
+ type: string
19187
+ enum: [agent, binding]
19188
+ resource_id:
19189
+ type: string
19190
+ format: uuid
19191
+ actor_id:
19192
+ type: string
19193
+ format: uuid
19194
+ before_json:
19195
+ type: object
19196
+ additionalProperties: true
19197
+ after_json:
19198
+ type: object
19199
+ additionalProperties: true
19200
+ change_kind:
19201
+ type: string
19202
+ enum: [narrowing, widening, neutral]
19203
+ approval_id:
19204
+ type: string
19205
+ format: uuid
19206
+ nullable: true
19207
+ created_at:
19208
+ type: string
19209
+ format: date-time
19210
+
19211
+ GuardrailReplayRequest:
19212
+ type: object
19213
+ properties:
19214
+ days:
19215
+ type: integer
19216
+ minimum: 1
19217
+ maximum: 90
19218
+ draft_guardrails:
19219
+ type: object
19220
+ additionalProperties: true
19221
+ draft_approval_policy:
19222
+ type: object
19223
+ additionalProperties: true
19224
+
19225
+ GuardrailReplayResponse:
19226
+ type: object
19227
+ properties:
19228
+ agent_id:
19229
+ type: string
19230
+ format: uuid
19231
+ window_days:
19232
+ type: integer
19233
+ format: int64
19234
+ allowed:
19235
+ type: integer
19236
+ format: int64
19237
+ denied:
19238
+ type: integer
19239
+ format: int64
19240
+ would_require_approval:
19241
+ type: integer
19242
+ format: int64
19243
+ samples:
19244
+ type: array
19245
+ items:
19246
+ type: object
19247
+ additionalProperties: true
19248
+
19249
+ AgentAccountListResponse:
19250
+ type: object
19251
+ properties:
19252
+ accounts:
19253
+ type: array
19254
+ items:
19255
+ $ref: "#/components/schemas/AgentAccountResponse"
19256
+
19257
+ AgentAccountResponse:
19258
+ type: object
19259
+ properties:
19260
+ id:
19261
+ type: string
19262
+ format: uuid
19263
+ org_id:
19264
+ type: string
19265
+ format: uuid
19266
+ agent_id:
19267
+ type: string
19268
+ format: uuid
19269
+ chain:
19270
+ type: string
19271
+ account_type:
19272
+ type: string
19273
+ address:
19274
+ type: string
19275
+ safe_version:
19276
+ type: string
19277
+ modules_enabled:
19278
+ type: array
19279
+ items:
19280
+ type: string
19281
+ deploy_status:
19282
+ type: string
19283
+ cosign_enabled:
19284
+ type: boolean
19285
+ metadata:
19286
+ type: object
19287
+ created_at:
19288
+ type: string
19289
+ format: date-time
19290
+ updated_at:
19291
+ type: string
19292
+ format: date-time
19293
+
19294
+ MigrationPlanResponse:
19295
+ type: object
19296
+ properties:
19297
+ agent_id:
19298
+ type: string
19299
+ format: uuid
19300
+ chain:
19301
+ type: string
19302
+ safe_address:
19303
+ type: string
19304
+ safe_version:
19305
+ type: string
19306
+ modules:
19307
+ type: array
19308
+ items:
19309
+ type: string
19310
+ eoa_address:
19311
+ type: string
19312
+ sweep_instructions:
19313
+ type: array
19314
+ items:
19315
+ type: object
19316
+ properties:
19317
+ asset:
19318
+ type: string
19319
+ action:
19320
+ type: string
19321
+ note:
19322
+ type: string
19323
+ roles_config_hash:
19324
+ type: string
19325
+ allowance_config_hash:
19326
+ type: string
19327
+ warnings:
19328
+ type: array
19329
+ items:
19330
+ type: string
19331
+ deploy_status:
19332
+ type: string
19333
+
19334
+ ProvisionAgentAccountRequest:
19335
+ type: object
19336
+ required: [chain]
19337
+ properties:
19338
+ chain:
19339
+ type: string
19340
+ account_type:
19341
+ type: string
19342
+ default: eoa
19343
+ address:
19344
+ type: string
19345
+
19346
+ SafeModuleRegistryResponse:
19347
+ type: object
19348
+ properties:
19349
+ chain:
19350
+ type: string
19351
+ modules:
19352
+ type: array
19353
+ items:
19354
+ $ref: "#/components/schemas/SafeModuleInfo"
19355
+
19356
+ SafeModuleInfo:
19357
+ type: object
19358
+ properties:
19359
+ name:
19360
+ type: string
19361
+ address:
19362
+ type: string
19363
+ version:
19364
+ type: string
19365
+
19366
+ AllowanceReconcileReport:
19367
+ type: object
19368
+ properties:
19369
+ org_id:
19370
+ type: string
19371
+ format: uuid
19372
+ agents_checked:
19373
+ type: integer
19374
+ compiled:
19375
+ type: array
19376
+ items:
19377
+ type: object
19378
+ additionalProperties: true
19379
+ drift_detected:
19380
+ type: array
19381
+ items:
19382
+ type: object
19383
+ additionalProperties: true
19384
+ onchain_sync:
19385
+ type: string
19386
+ description: counterfactual when on-chain broadcast is stubbed pre-audit
19387
+
19388
+ NotImplementedResponse:
19389
+ type: object
19390
+ required: [error, phase, message]
19391
+ properties:
19392
+ error:
19393
+ type: string
19394
+ phase:
19395
+ type: string
19396
+ message:
19397
+ type: string
19398
+
18375
19399
  # -------------------------------------------------------------------
18376
19400
  # Contract ABIs
18377
19401
  # -------------------------------------------------------------------