@1claw/openapi-spec 0.55.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 +6867 -5551
  3. package/openapi.yaml +909 -38
  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,6 +3962,34 @@ paths:
3636
3962
  "404":
3637
3963
  description: Agent-keys vault not found
3638
3964
 
3965
+ /v1/org/status:
3966
+ get:
3967
+ tags: [Organization]
3968
+ summary: Organization operational status
3969
+ description: Returns whether the org is emergency-frozen (blocks agent tx/execution).
3970
+ operationId: getOrgStatus
3971
+ responses:
3972
+ "200":
3973
+ description: Current org status
3974
+ content:
3975
+ application/json:
3976
+ schema:
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
+
3639
3993
  /v1/org/freeze:
3640
3994
  post:
3641
3995
  tags: [Organization]
@@ -5121,20 +5475,43 @@ paths:
5121
5475
  "403":
5122
5476
  $ref: "#/components/responses/Forbidden"
5123
5477
 
5124
- /v1/treasury/wallets/spend-policy:
5478
+ /v1/treasury/wallets/auth-policy:
5125
5479
  get:
5126
5480
  tags: [Treasury Wallets]
5127
- summary: Get effective spend policy for current user
5481
+ summary: Get effective human factor auth policy for embedded clients
5128
5482
  description: |
5129
- Returns the effective spend policy governing the authenticated user's
5130
- wallet transactions. Resolves from per-user override (if set) or the
5131
- app-wide default. Returns null if no policy is configured.
5132
- operationId: getEffectiveSpendPolicy
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
5133
5489
  security:
5134
5490
  - BearerAuth: []
5135
5491
  responses:
5136
5492
  "200":
5137
- description: Effective spend policy
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
+
5501
+ /v1/treasury/wallets/spend-policy:
5502
+ get:
5503
+ tags: [Treasury Wallets]
5504
+ summary: Get effective spend policy for current user
5505
+ description: |
5506
+ Returns the effective spend policy governing the authenticated user's
5507
+ wallet transactions. Resolves from per-user override (if set) or the
5508
+ app-wide default. Returns null if no policy is configured.
5509
+ operationId: getEffectiveSpendPolicy
5510
+ security:
5511
+ - BearerAuth: []
5512
+ responses:
5513
+ "200":
5514
+ description: Effective spend policy
5138
5515
  content:
5139
5516
  application/json:
5140
5517
  schema:
@@ -6945,9 +7322,10 @@ paths:
6945
7322
  tags: [Authentication]
6946
7323
  summary: Begin passkey transaction authorization
6947
7324
  description: |
6948
- Requires `tx_digest` — SHA-256 hex of canonical `chain|to|value_wei|data`
6949
- for the treasury send being authorized. The server recomputes this digest
6950
- 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.
6951
7329
  operationId: passkeyTxAssertBegin
6952
7330
  security:
6953
7331
  - BearerAuth: []
@@ -6956,17 +7334,20 @@ paths:
6956
7334
  content:
6957
7335
  application/json:
6958
7336
  schema:
6959
- type: object
6960
- required: [tx_digest]
6961
- properties:
6962
- tx_digest:
6963
- type: string
6964
- description: 64-char hex SHA-256 of canonical send params
7337
+ $ref: "#/components/schemas/PasskeyTxAssertBeginRequest"
6965
7338
  responses:
6966
7339
  "200":
6967
7340
  description: WebAuthn challenge
7341
+ content:
7342
+ application/json:
7343
+ schema:
7344
+ $ref: "#/components/schemas/PasskeyAssertBeginResponse"
6968
7345
  "400":
6969
- 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
6970
7351
 
6971
7352
  /v1/auth/passkeys/tx-assert/complete:
6972
7353
  post:
@@ -9731,6 +10112,59 @@ paths:
9731
10112
  "403":
9732
10113
  $ref: "#/components/responses/Forbidden"
9733
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
+
9734
10168
  # ---------------------------------------------------------------------------
9735
10169
  # Contract ABI Registry
9736
10170
  # ---------------------------------------------------------------------------
@@ -12016,7 +12450,9 @@ components:
12016
12450
  additionalProperties: true
12017
12451
  description: |
12018
12452
  Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron).
12019
- 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).
12020
12456
  Strictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.
12021
12457
  tx_max_per_day:
12022
12458
  type: integer
@@ -12330,7 +12766,8 @@ components:
12330
12766
  additionalProperties: true
12331
12767
  description: |
12332
12768
  Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron).
12333
- 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).
12334
12771
  Strictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.
12335
12772
  api_key_expires_at:
12336
12773
  type: string
@@ -12351,6 +12788,17 @@ components:
12351
12788
  type: object
12352
12789
  additionalProperties: true
12353
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.
12354
12802
 
12355
12803
  AgentResponse:
12356
12804
  type: object
@@ -12638,6 +13086,10 @@ components:
12638
13086
  type: object
12639
13087
  additionalProperties: true
12640
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`.
12641
13093
 
12642
13094
  KnownToken:
12643
13095
  type: object
@@ -16365,32 +16817,52 @@ components:
16365
16817
  format: date-time
16366
16818
  nullable: true
16367
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
+
16368
16856
  GuardrailViolation:
16369
16857
  type: object
16858
+ description: Convention 1 machine-readable guardrail denial JSON body.
16370
16859
  required: [error, reason_code, approval_available]
16371
16860
  properties:
16372
16861
  error:
16373
16862
  type: string
16374
16863
  enum: [guardrail_violation]
16375
16864
  reason_code:
16376
- type: string
16377
- enum:
16378
- - binding_rpm_exceeded
16379
- - agent_rpm_exceeded
16380
- - graphql_mutation_blocked
16381
- - graphql_depth_exceeded
16382
- - graphql_parse_failed
16383
- - graphql_introspection_blocked
16384
- - response_too_large
16385
- - request_too_large
16386
- - method_not_allowed
16387
- - header_not_allowed
16388
- - dns_private_ip_blocked
16389
- - agent_suspended
16390
- - outside_time_window
16391
- - secret_in_request
16392
- - concurrency_exceeded
16393
- - org_frozen
16865
+ $ref: "#/components/schemas/GuardrailReasonCode"
16394
16866
  limit:
16395
16867
  type: string
16396
16868
  nullable: true
@@ -16410,6 +16882,11 @@ components:
16410
16882
  type: string
16411
16883
  nullable: true
16412
16884
 
16885
+ GuardrailDenial:
16886
+ description: Alias of GuardrailViolation (Convention 1 JSON shape).
16887
+ allOf:
16888
+ - $ref: "#/components/schemas/GuardrailViolation"
16889
+
16413
16890
  # --- Email OTP ---
16414
16891
 
16415
16892
  EmailOtpVerifyResponse:
@@ -16532,6 +17009,13 @@ components:
16532
17009
  max_transactions_per_day:
16533
17010
  type: integer
16534
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.
16535
17019
 
16536
17020
  SpendPolicyResponse:
16537
17021
  type: object
@@ -16568,12 +17052,129 @@ components:
16568
17052
  max_transactions_per_day:
16569
17053
  type: integer
16570
17054
  nullable: true
17055
+ human_factor_auth:
17056
+ type: object
17057
+ additionalProperties: true
17058
+ nullable: true
16571
17059
  created_at:
16572
17060
  type: string
16573
17061
  format: date-time
16574
17062
 
16575
17063
  # --- Risk Engine ---
16576
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
+
16577
17178
  RiskEvent:
16578
17179
  type: object
16579
17180
  required: [id, occurred_at, principal_type, principal_id, org_id, event_type, payload, created_at]
@@ -16810,6 +17411,13 @@ components:
16810
17411
  description: "Legacy: inline credential value."
16811
17412
  credential_source:
16812
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.
16813
17421
 
16814
17422
  BindingGuardrails:
16815
17423
  type: object
@@ -18525,6 +19133,269 @@ components:
18525
19133
  type: string
18526
19134
  format: date-time
18527
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
+
18528
19399
  # -------------------------------------------------------------------
18529
19400
  # Contract ABIs
18530
19401
  # -------------------------------------------------------------------