@1claw/openapi-spec 0.55.0 → 0.57.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 +7 -1
  2. package/openapi.json +16180 -14098
  3. package/openapi.yaml +1520 -150
  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.57.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,
@@ -932,6 +932,8 @@ paths:
932
932
  properties:
933
933
  require_passkey_for_vaults:
934
934
  type: boolean
935
+ require_passkey_for_mfa:
936
+ type: boolean
935
937
  passkey_count:
936
938
  type: integer
937
939
  patch:
@@ -941,6 +943,10 @@ paths:
941
943
  Disabling `require_passkey_for_vaults` requires `X-Auth-Confirm`
942
944
  (purpose `security.vault_passkey.disable`) with a passkey or TOTP
943
945
  when either is enrolled.
946
+
947
+ Disabling `require_passkey_for_mfa` requires `X-Auth-Confirm`
948
+ (purpose `security.mfa_passkey.disable`) with a passkey or TOTP
949
+ when either is enrolled.
944
950
  operationId: updateSecuritySettings
945
951
  parameters:
946
952
  - name: X-Auth-Confirm
@@ -957,12 +963,51 @@ paths:
957
963
  properties:
958
964
  require_passkey_for_vaults:
959
965
  type: boolean
966
+ require_passkey_for_mfa:
967
+ type: boolean
960
968
  responses:
961
969
  "200":
962
970
  description: Updated settings
963
971
  "403":
964
972
  $ref: "#/components/responses/Forbidden"
965
973
 
974
+ /v1/auth/human-factor-auth:
975
+ get:
976
+ tags: [Authentication]
977
+ summary: Get effective human factor auth policy
978
+ description: |
979
+ Returns the resolved HFA policy for treasury wallet send, swap, and export.
980
+ Precedence: user override → spend policy → platform defaults.
981
+ operationId: getHumanFactorAuth
982
+ responses:
983
+ "200":
984
+ description: Effective HFA policy
985
+ content:
986
+ application/json:
987
+ schema:
988
+ $ref: "#/components/schemas/HumanFactorAuthResponse"
989
+ "403":
990
+ $ref: "#/components/responses/Forbidden"
991
+ put:
992
+ tags: [Authentication]
993
+ summary: Set user human factor auth policy
994
+ operationId: upsertHumanFactorAuth
995
+ requestBody:
996
+ required: true
997
+ content:
998
+ application/json:
999
+ schema:
1000
+ $ref: "#/components/schemas/UpsertHumanFactorAuthRequest"
1001
+ responses:
1002
+ "200":
1003
+ description: Updated policy
1004
+ content:
1005
+ application/json:
1006
+ schema:
1007
+ $ref: "#/components/schemas/HumanFactorAuthResponse"
1008
+ "403":
1009
+ $ref: "#/components/responses/Forbidden"
1010
+
966
1011
  # MFA
967
1012
 
968
1013
  /v1/auth/mfa/status:
@@ -1034,6 +1079,54 @@ paths:
1034
1079
  "401":
1035
1080
  $ref: "#/components/responses/Unauthorized"
1036
1081
 
1082
+ /v1/auth/mfa/passkey/begin:
1083
+ post:
1084
+ tags: [Authentication]
1085
+ summary: Begin passkey MFA verification during login
1086
+ operationId: mfaPasskeyBegin
1087
+ security: []
1088
+ requestBody:
1089
+ required: true
1090
+ content:
1091
+ application/json:
1092
+ schema:
1093
+ type: object
1094
+ required: [mfa_token]
1095
+ properties:
1096
+ mfa_token:
1097
+ type: string
1098
+ responses:
1099
+ "200":
1100
+ description: WebAuthn challenge
1101
+ content:
1102
+ application/json:
1103
+ schema:
1104
+ $ref: "#/components/schemas/PasskeyAssertBeginResponse"
1105
+ "400":
1106
+ $ref: "#/components/responses/BadRequest"
1107
+
1108
+ /v1/auth/mfa/passkey/complete:
1109
+ post:
1110
+ tags: [Authentication]
1111
+ summary: Complete passkey MFA verification during login
1112
+ operationId: mfaPasskeyComplete
1113
+ security: []
1114
+ requestBody:
1115
+ required: true
1116
+ content:
1117
+ application/json:
1118
+ schema:
1119
+ $ref: "#/components/schemas/MfaPasskeyCompleteRequest"
1120
+ responses:
1121
+ "200":
1122
+ description: MFA verified, JWT issued
1123
+ content:
1124
+ application/json:
1125
+ schema:
1126
+ $ref: "#/components/schemas/TokenResponse"
1127
+ "401":
1128
+ $ref: "#/components/responses/Unauthorized"
1129
+
1037
1130
  /v1/auth/mfa:
1038
1131
  delete:
1039
1132
  tags: [Authentication]
@@ -2331,6 +2424,16 @@ paths:
2331
2424
  application/json:
2332
2425
  schema:
2333
2426
  $ref: "#/components/schemas/AgentResponse"
2427
+ "202":
2428
+ description: |
2429
+ Guardrail widening queued for human approval. The change is not
2430
+ applied until approved via POST /v1/approvals/{approval_id}/decide.
2431
+ Resubmit this PATCH with `approval_id` set to the returned value
2432
+ after approval to apply the widening.
2433
+ content:
2434
+ application/json:
2435
+ schema:
2436
+ $ref: "#/components/schemas/GuardrailWideningQueuedResponse"
2334
2437
  "404":
2335
2438
  $ref: "#/components/responses/NotFound"
2336
2439
  delete:
@@ -2904,14 +3007,31 @@ paths:
2904
3007
  # Agent Delegations
2905
3008
  # ---------------------------------------------------------------------------
2906
3009
 
2907
- /v1/agents/{agent_id}/delegations:
3010
+ /v1/agents/{agent_id}/accounts:
3011
+ get:
3012
+ tags: [Agents]
3013
+ summary: List agent on-chain accounts
3014
+ operationId: listAgentAccounts
3015
+ parameters:
3016
+ - $ref: "#/components/parameters/AgentId"
3017
+ responses:
3018
+ "200":
3019
+ description: Agent accounts
3020
+ content:
3021
+ application/json:
3022
+ schema:
3023
+ $ref: "#/components/schemas/AgentAccountListResponse"
3024
+ "401":
3025
+ $ref: "#/components/responses/Unauthorized"
3026
+ "403":
3027
+ $ref: "#/components/responses/Forbidden"
3028
+ "404":
3029
+ $ref: "#/components/responses/NotFound"
2908
3030
  post:
2909
- tags: [Delegations]
2910
- summary: Create a delegation
2911
- description: |
2912
- Grant an agent (delegator) permission to delegate tasks to another agent (delegate).
2913
- Human-only — agents cannot create their own delegations.
2914
- operationId: createDelegation
3031
+ tags: [Agents]
3032
+ summary: Provision an agent account record
3033
+ description: Human-only. Creates a DB record for an EOA or Safe account (Safe onchain sync is stubbed).
3034
+ operationId: provisionAgentAccount
2915
3035
  parameters:
2916
3036
  - $ref: "#/components/parameters/AgentId"
2917
3037
  requestBody:
@@ -2919,159 +3039,412 @@ paths:
2919
3039
  content:
2920
3040
  application/json:
2921
3041
  schema:
2922
- $ref: "#/components/schemas/CreateDelegationRequest"
3042
+ $ref: "#/components/schemas/ProvisionAgentAccountRequest"
2923
3043
  responses:
2924
3044
  "201":
2925
- description: Delegation created
3045
+ description: Account provisioned
2926
3046
  content:
2927
3047
  application/json:
2928
3048
  schema:
2929
- $ref: "#/components/schemas/DelegationResponse"
2930
- "400":
2931
- $ref: "#/components/responses/BadRequest"
3049
+ $ref: "#/components/schemas/AgentAccountResponse"
3050
+ "401":
3051
+ $ref: "#/components/responses/Unauthorized"
2932
3052
  "403":
2933
3053
  $ref: "#/components/responses/Forbidden"
2934
- "409":
2935
- description: Delegation already exists for this delegator/delegate pair
2936
- content:
2937
- application/json:
2938
- schema:
2939
- $ref: "#/components/schemas/ProblemDetails"
2940
- get:
2941
- tags: [Delegations]
2942
- summary: List delegations for an agent
2943
- description: |
2944
- List all delegations where this agent is the delegator.
2945
- operationId: listDelegations
2946
- parameters:
2947
- - $ref: "#/components/parameters/AgentId"
2948
- responses:
2949
- "200":
2950
- description: List of delegations
2951
- content:
2952
- application/json:
2953
- schema:
2954
- $ref: "#/components/schemas/DelegationListResponse"
2955
3054
  "404":
2956
3055
  $ref: "#/components/responses/NotFound"
2957
3056
 
2958
- /v1/agents/{agent_id}/delegations/effective:
2959
- get:
2960
- tags: [Delegations]
2961
- summary: Get effective delegations
2962
- description: |
2963
- Get the effective delegations for an agent, including daily usage statistics.
2964
- Agents can call this on their own ID to discover what they are authorized to delegate to.
2965
- operationId: getEffectiveDelegations
3057
+ /v1/agents/{agent_id}/accounts/migrate:
3058
+ post:
3059
+ tags: [Agents]
3060
+ summary: EOA to Safe migration wizard
3061
+ description: Human-only. Provisions counterfactual Safe and returns sweep plan. Onchain module broadcast stubbed pre-audit.
3062
+ operationId: migrateAgentToSafe
2966
3063
  parameters:
2967
3064
  - $ref: "#/components/parameters/AgentId"
3065
+ requestBody:
3066
+ required: true
3067
+ content:
3068
+ application/json:
3069
+ schema:
3070
+ type: object
3071
+ required: [chain]
3072
+ properties:
3073
+ chain:
3074
+ type: string
3075
+ deprecate_eoa:
3076
+ type: boolean
2968
3077
  responses:
2969
3078
  "200":
2970
- description: Effective delegations with usage stats
3079
+ description: Migration plan
2971
3080
  content:
2972
3081
  application/json:
2973
3082
  schema:
2974
- $ref: "#/components/schemas/DelegationListResponse"
3083
+ $ref: "#/components/schemas/MigrationPlanResponse"
3084
+ "401":
3085
+ $ref: "#/components/responses/Unauthorized"
3086
+ "403":
3087
+ $ref: "#/components/responses/Forbidden"
2975
3088
  "404":
2976
3089
  $ref: "#/components/responses/NotFound"
2977
3090
 
2978
- /v1/agents/{agent_id}/delegations/{delegation_id}:
2979
- get:
2980
- tags: [Delegations]
2981
- summary: Get a specific delegation
2982
- operationId: getDelegation
3091
+ /v1/agents/{agent_id}/accounts/{chain}/deprecate-eoa:
3092
+ post:
3093
+ tags: [Agents]
3094
+ summary: Mark agent EOA account deprecated
3095
+ operationId: deprecateAgentEoa
2983
3096
  parameters:
2984
3097
  - $ref: "#/components/parameters/AgentId"
2985
- - name: delegation_id
3098
+ - name: chain
2986
3099
  in: path
2987
3100
  required: true
2988
3101
  schema:
2989
3102
  type: string
2990
- format: uuid
2991
3103
  responses:
2992
3104
  "200":
2993
- description: Delegation details
3105
+ description: Updated account
2994
3106
  content:
2995
3107
  application/json:
2996
3108
  schema:
2997
- $ref: "#/components/schemas/DelegationResponse"
3109
+ $ref: "#/components/schemas/AgentAccountResponse"
3110
+ "401":
3111
+ $ref: "#/components/responses/Unauthorized"
3112
+ "403":
3113
+ $ref: "#/components/responses/Forbidden"
2998
3114
  "404":
2999
3115
  $ref: "#/components/responses/NotFound"
3000
- patch:
3001
- tags: [Delegations]
3002
- summary: Update a delegation
3003
- description: |
3004
- Update delegation tools, limits, mode, or active status. Human-only.
3005
- operationId: updateDelegation
3116
+
3117
+ /v1/agents/{agent_id}/accounts/{chain}/deploy:
3118
+ post:
3119
+ tags: [Agents]
3120
+ summary: Lazy-deploy counterfactual Safe (stub)
3121
+ description: Human-only. Broadcasts Safe deployment when Guard audit completes. Returns 501 pre-audit.
3122
+ operationId: deployAgentSafeAccount
3006
3123
  parameters:
3007
3124
  - $ref: "#/components/parameters/AgentId"
3008
- - name: delegation_id
3125
+ - name: chain
3009
3126
  in: path
3010
3127
  required: true
3011
3128
  schema:
3012
3129
  type: string
3013
- format: uuid
3014
- requestBody:
3015
- required: true
3016
- content:
3017
- application/json:
3018
- schema:
3019
- $ref: "#/components/schemas/UpdateDelegationRequest"
3020
3130
  responses:
3021
- "200":
3022
- description: Delegation updated
3131
+ "501":
3132
+ description: Not implemented (Phase 5.1)
3023
3133
  content:
3024
3134
  application/json:
3025
3135
  schema:
3026
- $ref: "#/components/schemas/DelegationResponse"
3027
- "400":
3028
- $ref: "#/components/responses/BadRequest"
3136
+ $ref: "#/components/schemas/NotImplementedResponse"
3137
+ "401":
3138
+ $ref: "#/components/responses/Unauthorized"
3029
3139
  "403":
3030
3140
  $ref: "#/components/responses/Forbidden"
3031
3141
  "404":
3032
3142
  $ref: "#/components/responses/NotFound"
3033
- delete:
3034
- tags: [Delegations]
3035
- summary: Revoke a delegation
3036
- operationId: revokeDelegation
3143
+
3144
+ /v1/org/safe/sync-allowances:
3145
+ post:
3146
+ tags: [Organization]
3147
+ summary: Reconcile Safe allowance targets (org admin)
3148
+ description: Compiles tx_daily_limit targets for Safe agents. Onchain read/write stubbed pre-audit.
3149
+ operationId: syncOrgSafeAllowances
3150
+ responses:
3151
+ "200":
3152
+ description: Reconciliation report
3153
+ content:
3154
+ application/json:
3155
+ schema:
3156
+ $ref: "#/components/schemas/AllowanceReconcileReport"
3157
+ "401":
3158
+ $ref: "#/components/responses/Unauthorized"
3159
+ "403":
3160
+ $ref: "#/components/responses/Forbidden"
3161
+
3162
+ /v1/treasury/{treasury_id}/safe/roles-sync:
3163
+ post:
3164
+ tags: [Treasury]
3165
+ summary: Sync treasury Safe Roles module (stub)
3166
+ description: Human-only. Reconciles on-chain Roles config with agent guardrails. Returns 501 pre-audit.
3167
+ operationId: treasurySafeRolesSync
3037
3168
  parameters:
3038
- - $ref: "#/components/parameters/AgentId"
3039
- - name: delegation_id
3169
+ - name: treasury_id
3040
3170
  in: path
3041
3171
  required: true
3042
3172
  schema:
3043
3173
  type: string
3044
3174
  format: uuid
3045
3175
  responses:
3046
- "204":
3047
- description: Delegation revoked
3176
+ "501":
3177
+ description: Not implemented (Phase 5.9)
3178
+ content:
3179
+ application/json:
3180
+ schema:
3181
+ $ref: "#/components/schemas/NotImplementedResponse"
3182
+ "401":
3183
+ $ref: "#/components/responses/Unauthorized"
3184
+ "403":
3185
+ $ref: "#/components/responses/Forbidden"
3048
3186
  "404":
3049
3187
  $ref: "#/components/responses/NotFound"
3050
3188
 
3051
- # ---------------------------------------------------------------------------
3052
- # Unified Signing Intent
3053
- # ---------------------------------------------------------------------------
3189
+ /v1/agents/{agent_id}/safe/cosign:
3190
+ post:
3191
+ tags: [Agents]
3192
+ summary: Enable Vault co-signer (stub)
3193
+ operationId: enableSafeCosign
3194
+ parameters:
3195
+ - $ref: "#/components/parameters/AgentId"
3196
+ responses:
3197
+ "501":
3198
+ description: Not implemented (Phase 5.2)
3054
3199
 
3055
- /v1/agents/{agent_id}/sign:
3200
+ /v1/agents/{agent_id}/safe/passkey-enroll:
3056
3201
  post:
3057
- tags: [Signing]
3058
- summary: Unified signing intent (EIP-191, EIP-712, EIP-2718 types 0-4)
3059
- operationId: signIntent
3202
+ tags: [Agents]
3203
+ summary: Enroll passkey Safe owner (stub)
3204
+ operationId: enrollSafePasskeyOwner
3205
+ parameters:
3206
+ - $ref: "#/components/parameters/AgentId"
3207
+ responses:
3208
+ "501":
3209
+ description: Not implemented (Phase 5.5)
3210
+
3211
+ /v1/agents/{agent_id}/safe/timelock:
3212
+ post:
3213
+ tags: [Agents]
3214
+ summary: Configure Zodiac timelock (stub)
3215
+ operationId: configureSafeTimelock
3216
+ parameters:
3217
+ - $ref: "#/components/parameters/AgentId"
3218
+ responses:
3219
+ "501":
3220
+ description: Not implemented (Phase 5.6)
3221
+
3222
+ /v1/agents/{agent_id}/safe/erc4337:
3223
+ post:
3224
+ tags: [Agents]
3225
+ summary: Enable ERC-4337 Safe lane (stub)
3226
+ operationId: enableSafeErc4337
3227
+ parameters:
3228
+ - $ref: "#/components/parameters/AgentId"
3229
+ responses:
3230
+ "501":
3231
+ description: Not implemented (Phase 5.8)
3232
+
3233
+ /v1/agents/{agent_id}/guardrails/replay:
3234
+ post:
3235
+ tags: [Agents]
3236
+ summary: Dry-run guardrail changes against recent transactions
3237
+ description: Human-only. Compares draft guardrails against recent agent transactions.
3238
+ operationId: replayAgentGuardrails
3060
3239
  parameters:
3061
3240
  - $ref: "#/components/parameters/AgentId"
3062
3241
  requestBody:
3063
- required: true
3064
3242
  content:
3065
3243
  application/json:
3066
3244
  schema:
3067
- $ref: "#/components/schemas/SignIntentRequest"
3245
+ $ref: "#/components/schemas/GuardrailReplayRequest"
3068
3246
  responses:
3069
3247
  "200":
3070
- description: Signed result
3248
+ description: Replay report
3071
3249
  content:
3072
3250
  application/json:
3073
3251
  schema:
3074
- $ref: "#/components/schemas/SignIntentResponse"
3252
+ $ref: "#/components/schemas/GuardrailReplayResponse"
3253
+ "401":
3254
+ $ref: "#/components/responses/Unauthorized"
3255
+ "403":
3256
+ $ref: "#/components/responses/Forbidden"
3257
+ "404":
3258
+ $ref: "#/components/responses/NotFound"
3259
+
3260
+ /v1/safe/module-registry/{chain}:
3261
+ get:
3262
+ tags: [Agents]
3263
+ summary: List Safe module registry entries for a chain
3264
+ operationId: getSafeModuleRegistry
3265
+ security: []
3266
+ parameters:
3267
+ - name: chain
3268
+ in: path
3269
+ required: true
3270
+ schema:
3271
+ type: string
3272
+ responses:
3273
+ "200":
3274
+ description: Module registry
3275
+ content:
3276
+ application/json:
3277
+ schema:
3278
+ $ref: "#/components/schemas/SafeModuleRegistryResponse"
3279
+
3280
+ /v1/agents/{agent_id}/delegations:
3281
+ post:
3282
+ tags: [Delegations]
3283
+ summary: Create a delegation
3284
+ description: |
3285
+ Grant an agent (delegator) permission to delegate tasks to another agent (delegate).
3286
+ Human-only — agents cannot create their own delegations.
3287
+ operationId: createDelegation
3288
+ parameters:
3289
+ - $ref: "#/components/parameters/AgentId"
3290
+ requestBody:
3291
+ required: true
3292
+ content:
3293
+ application/json:
3294
+ schema:
3295
+ $ref: "#/components/schemas/CreateDelegationRequest"
3296
+ responses:
3297
+ "201":
3298
+ description: Delegation created
3299
+ content:
3300
+ application/json:
3301
+ schema:
3302
+ $ref: "#/components/schemas/DelegationResponse"
3303
+ "400":
3304
+ $ref: "#/components/responses/BadRequest"
3305
+ "403":
3306
+ $ref: "#/components/responses/Forbidden"
3307
+ "409":
3308
+ description: Delegation already exists for this delegator/delegate pair
3309
+ content:
3310
+ application/json:
3311
+ schema:
3312
+ $ref: "#/components/schemas/ProblemDetails"
3313
+ get:
3314
+ tags: [Delegations]
3315
+ summary: List delegations for an agent
3316
+ description: |
3317
+ List all delegations where this agent is the delegator.
3318
+ operationId: listDelegations
3319
+ parameters:
3320
+ - $ref: "#/components/parameters/AgentId"
3321
+ responses:
3322
+ "200":
3323
+ description: List of delegations
3324
+ content:
3325
+ application/json:
3326
+ schema:
3327
+ $ref: "#/components/schemas/DelegationListResponse"
3328
+ "404":
3329
+ $ref: "#/components/responses/NotFound"
3330
+
3331
+ /v1/agents/{agent_id}/delegations/effective:
3332
+ get:
3333
+ tags: [Delegations]
3334
+ summary: Get effective delegations
3335
+ description: |
3336
+ Get the effective delegations for an agent, including daily usage statistics.
3337
+ Agents can call this on their own ID to discover what they are authorized to delegate to.
3338
+ operationId: getEffectiveDelegations
3339
+ parameters:
3340
+ - $ref: "#/components/parameters/AgentId"
3341
+ responses:
3342
+ "200":
3343
+ description: Effective delegations with usage stats
3344
+ content:
3345
+ application/json:
3346
+ schema:
3347
+ $ref: "#/components/schemas/DelegationListResponse"
3348
+ "404":
3349
+ $ref: "#/components/responses/NotFound"
3350
+
3351
+ /v1/agents/{agent_id}/delegations/{delegation_id}:
3352
+ get:
3353
+ tags: [Delegations]
3354
+ summary: Get a specific delegation
3355
+ operationId: getDelegation
3356
+ parameters:
3357
+ - $ref: "#/components/parameters/AgentId"
3358
+ - name: delegation_id
3359
+ in: path
3360
+ required: true
3361
+ schema:
3362
+ type: string
3363
+ format: uuid
3364
+ responses:
3365
+ "200":
3366
+ description: Delegation details
3367
+ content:
3368
+ application/json:
3369
+ schema:
3370
+ $ref: "#/components/schemas/DelegationResponse"
3371
+ "404":
3372
+ $ref: "#/components/responses/NotFound"
3373
+ patch:
3374
+ tags: [Delegations]
3375
+ summary: Update a delegation
3376
+ description: |
3377
+ Update delegation tools, limits, mode, or active status. Human-only.
3378
+ operationId: updateDelegation
3379
+ parameters:
3380
+ - $ref: "#/components/parameters/AgentId"
3381
+ - name: delegation_id
3382
+ in: path
3383
+ required: true
3384
+ schema:
3385
+ type: string
3386
+ format: uuid
3387
+ requestBody:
3388
+ required: true
3389
+ content:
3390
+ application/json:
3391
+ schema:
3392
+ $ref: "#/components/schemas/UpdateDelegationRequest"
3393
+ responses:
3394
+ "200":
3395
+ description: Delegation updated
3396
+ content:
3397
+ application/json:
3398
+ schema:
3399
+ $ref: "#/components/schemas/DelegationResponse"
3400
+ "400":
3401
+ $ref: "#/components/responses/BadRequest"
3402
+ "403":
3403
+ $ref: "#/components/responses/Forbidden"
3404
+ "404":
3405
+ $ref: "#/components/responses/NotFound"
3406
+ delete:
3407
+ tags: [Delegations]
3408
+ summary: Revoke a delegation
3409
+ operationId: revokeDelegation
3410
+ parameters:
3411
+ - $ref: "#/components/parameters/AgentId"
3412
+ - name: delegation_id
3413
+ in: path
3414
+ required: true
3415
+ schema:
3416
+ type: string
3417
+ format: uuid
3418
+ responses:
3419
+ "204":
3420
+ description: Delegation revoked
3421
+ "404":
3422
+ $ref: "#/components/responses/NotFound"
3423
+
3424
+ # ---------------------------------------------------------------------------
3425
+ # Unified Signing Intent
3426
+ # ---------------------------------------------------------------------------
3427
+
3428
+ /v1/agents/{agent_id}/sign:
3429
+ post:
3430
+ tags: [Signing]
3431
+ summary: Unified signing intent (EIP-191, EIP-712, EIP-2718 types 0-4)
3432
+ operationId: signIntent
3433
+ parameters:
3434
+ - $ref: "#/components/parameters/AgentId"
3435
+ requestBody:
3436
+ required: true
3437
+ content:
3438
+ application/json:
3439
+ schema:
3440
+ $ref: "#/components/schemas/SignIntentRequest"
3441
+ responses:
3442
+ "200":
3443
+ description: Signed result
3444
+ content:
3445
+ application/json:
3446
+ schema:
3447
+ $ref: "#/components/schemas/SignIntentResponse"
3075
3448
  "400":
3076
3449
  $ref: "#/components/responses/BadRequest"
3077
3450
  "403":
@@ -3174,6 +3547,15 @@ paths:
3174
3547
  application/json:
3175
3548
  schema:
3176
3549
  $ref: "#/components/schemas/BindingResponse"
3550
+ "202":
3551
+ description: |
3552
+ Binding guardrail widening queued for human approval. Resubmit
3553
+ PATCH with `approval_id` after approval via
3554
+ POST /v1/approvals/{approval_id}/decide.
3555
+ content:
3556
+ application/json:
3557
+ schema:
3558
+ $ref: "#/components/schemas/GuardrailWideningQueuedResponse"
3177
3559
  "400":
3178
3560
  $ref: "#/components/responses/BadRequest"
3179
3561
  "404":
@@ -3636,6 +4018,34 @@ paths:
3636
4018
  "404":
3637
4019
  description: Agent-keys vault not found
3638
4020
 
4021
+ /v1/org/status:
4022
+ get:
4023
+ tags: [Organization]
4024
+ summary: Organization operational status
4025
+ description: Returns whether the org is emergency-frozen (blocks agent tx/execution).
4026
+ operationId: getOrgStatus
4027
+ responses:
4028
+ "200":
4029
+ description: Current org status
4030
+ content:
4031
+ application/json:
4032
+ schema:
4033
+ type: object
4034
+ required: [org_id, status]
4035
+ properties:
4036
+ org_id:
4037
+ type: string
4038
+ format: uuid
4039
+ status:
4040
+ type: string
4041
+ enum: [active, frozen]
4042
+ frozen_at:
4043
+ type: string
4044
+ format: date-time
4045
+ nullable: true
4046
+ "403":
4047
+ description: Forbidden
4048
+
3639
4049
  /v1/org/freeze:
3640
4050
  post:
3641
4051
  tags: [Organization]
@@ -5121,6 +5531,29 @@ paths:
5121
5531
  "403":
5122
5532
  $ref: "#/components/responses/Forbidden"
5123
5533
 
5534
+ /v1/treasury/wallets/auth-policy:
5535
+ get:
5536
+ tags: [Treasury Wallets]
5537
+ summary: Get effective human factor auth policy for embedded clients
5538
+ description: |
5539
+ Returns the resolved human factor auth (HFA) policy governing treasury
5540
+ wallet send, swap, and export, plus the number of passkeys registered
5541
+ for the calling user. Intended for embedded wallet clients; equivalent
5542
+ to GET /v1/auth/human-factor-auth with an additional passkey count.
5543
+ Precedence: user override → platform app → spend policy → defaults.
5544
+ operationId: getTreasuryAuthPolicy
5545
+ security:
5546
+ - BearerAuth: []
5547
+ responses:
5548
+ "200":
5549
+ description: Effective HFA policy with passkey registration count
5550
+ content:
5551
+ application/json:
5552
+ schema:
5553
+ $ref: "#/components/schemas/TreasuryAuthPolicyResponse"
5554
+ "403":
5555
+ $ref: "#/components/responses/Forbidden"
5556
+
5124
5557
  /v1/treasury/wallets/spend-policy:
5125
5558
  get:
5126
5559
  tags: [Treasury Wallets]
@@ -5147,6 +5580,28 @@ paths:
5147
5580
  "401":
5148
5581
  $ref: "#/components/responses/Unauthorized"
5149
5582
 
5583
+ /v1/treasury/wallets/inference-budget:
5584
+ get:
5585
+ tags: [Treasury Wallets]
5586
+ summary: Get inference budget for current user
5587
+ description: |
5588
+ Returns the user's remaining LLM inference allowance when connected via a platform app.
5589
+ Includes allowance, spent, remaining USD, per-request cap, and billing period end.
5590
+ operationId: getUserInferenceBudget
5591
+ security:
5592
+ - BearerAuth: []
5593
+ responses:
5594
+ "200":
5595
+ description: Inference budget (or unconfigured message)
5596
+ content:
5597
+ application/json:
5598
+ schema:
5599
+ oneOf:
5600
+ - $ref: "#/components/schemas/InferenceBudgetResponse"
5601
+ - $ref: "#/components/schemas/InferenceBudgetUnconfiguredResponse"
5602
+ "403":
5603
+ $ref: "#/components/responses/Forbidden"
5604
+
5150
5605
  # ---------------------------------------------------------------------------
5151
5606
  # Webhooks
5152
5607
  # ---------------------------------------------------------------------------
@@ -5993,23 +6448,61 @@ paths:
5993
6448
  "404":
5994
6449
  $ref: "#/components/responses/NotFound"
5995
6450
 
5996
- /v1/platform/users/upsert:
6451
+ /v1/platform/apps/{appId}/templates/{template_id}/preview:
5997
6452
  post:
5998
6453
  tags: [Platform]
5999
- summary: Provision or look up a platform user
6000
- description: Upserts a user using either an OIDC subject_token (verified against the platform app's JWKS) or an email address. Returns the user handle and connection ID.
6454
+ summary: Preview resolved template spec
6455
+ description: |
6456
+ Resolves `{{params.*}}` and `{{subject.*}}` placeholders in a template spec
6457
+ without provisioning resources. Useful for validating parameterized bootstrap templates.
6001
6458
  security:
6002
6459
  - BearerAuth: []
6003
- requestBody:
6004
- required: true
6005
- content:
6006
- application/json:
6007
- schema:
6008
- $ref: "#/components/schemas/UpsertPlatformUserRequest"
6009
- responses:
6010
- "200":
6011
- description: Existing user found
6012
- content:
6460
+ parameters:
6461
+ - in: path
6462
+ name: appId
6463
+ required: true
6464
+ schema:
6465
+ type: string
6466
+ format: uuid
6467
+ - in: path
6468
+ name: template_id
6469
+ required: true
6470
+ schema:
6471
+ type: string
6472
+ format: uuid
6473
+ requestBody:
6474
+ required: false
6475
+ content:
6476
+ application/json:
6477
+ schema:
6478
+ $ref: "#/components/schemas/TemplatePreviewRequest"
6479
+ responses:
6480
+ "200":
6481
+ description: Resolved template spec
6482
+ content:
6483
+ application/json:
6484
+ schema:
6485
+ $ref: "#/components/schemas/TemplatePreviewResponse"
6486
+ "404":
6487
+ $ref: "#/components/responses/NotFound"
6488
+
6489
+ /v1/platform/users/upsert:
6490
+ post:
6491
+ tags: [Platform]
6492
+ summary: Provision or look up a platform user
6493
+ description: Upserts a user using either an OIDC subject_token (verified against the platform app's JWKS) or an email address. Returns the user handle and connection ID.
6494
+ security:
6495
+ - BearerAuth: []
6496
+ requestBody:
6497
+ required: true
6498
+ content:
6499
+ application/json:
6500
+ schema:
6501
+ $ref: "#/components/schemas/UpsertPlatformUserRequest"
6502
+ responses:
6503
+ "200":
6504
+ description: Existing user found
6505
+ content:
6013
6506
  application/json:
6014
6507
  schema:
6015
6508
  $ref: "#/components/schemas/PlatformUserResponse"
@@ -6026,6 +6519,31 @@ paths:
6026
6519
  schema:
6027
6520
  $ref: "#/components/schemas/PlatformUserLinkRequiredResponse"
6028
6521
 
6522
+ /v1/platform/siwe/challenge:
6523
+ post:
6524
+ tags: [Platform]
6525
+ summary: Issue SIWE nonce
6526
+ description: |
6527
+ Creates a one-time nonce for Sign-In With Ethereum user provisioning.
6528
+ Requires platform (`plt_`) authentication. The nonce expires in 5 minutes.
6529
+ security:
6530
+ - BearerAuth: []
6531
+ requestBody:
6532
+ required: false
6533
+ content:
6534
+ application/json:
6535
+ schema:
6536
+ $ref: "#/components/schemas/SiweChallengeRequest"
6537
+ responses:
6538
+ "200":
6539
+ description: Nonce issued
6540
+ content:
6541
+ application/json:
6542
+ schema:
6543
+ $ref: "#/components/schemas/SiweChallengeResponse"
6544
+ "400":
6545
+ description: SIWE domain not configured
6546
+
6029
6547
  /v1/platform/apps/{appId}/users:
6030
6548
  get:
6031
6549
  tags: [Platform]
@@ -6125,6 +6643,100 @@ paths:
6125
6643
  "404":
6126
6644
  description: Connection not found
6127
6645
 
6646
+ /v1/platform/connections/{connectionId}:
6647
+ get:
6648
+ tags: [Platform]
6649
+ summary: Get connection details
6650
+ description: |
6651
+ Returns connection status, claim state, wallet address, and provisioned resource IDs.
6652
+ Use for polling the claim loop after bootstrap.
6653
+ security:
6654
+ - BearerAuth: []
6655
+ parameters:
6656
+ - in: path
6657
+ name: connectionId
6658
+ required: true
6659
+ schema:
6660
+ type: string
6661
+ format: uuid
6662
+ responses:
6663
+ "200":
6664
+ description: Connection details
6665
+ content:
6666
+ application/json:
6667
+ schema:
6668
+ $ref: "#/components/schemas/ConnectionDetailResponse"
6669
+ "404":
6670
+ $ref: "#/components/responses/NotFound"
6671
+
6672
+ /v1/platform/connections/{connectionId}/usage:
6673
+ get:
6674
+ tags: [Platform]
6675
+ summary: Get per-connection usage
6676
+ description: Returns inference spend for the current UTC month for this connection.
6677
+ security:
6678
+ - BearerAuth: []
6679
+ parameters:
6680
+ - in: path
6681
+ name: connectionId
6682
+ required: true
6683
+ schema:
6684
+ type: string
6685
+ format: uuid
6686
+ responses:
6687
+ "200":
6688
+ description: Usage summary
6689
+ content:
6690
+ application/json:
6691
+ schema:
6692
+ $ref: "#/components/schemas/ConnectionUsageResponse"
6693
+ "404":
6694
+ $ref: "#/components/responses/NotFound"
6695
+
6696
+ /v1/platform/connections/{connectionId}/entitlements:
6697
+ get:
6698
+ tags: [Platform]
6699
+ summary: List entitlement evaluations
6700
+ description: Returns on-chain entitlement watch status for the connection.
6701
+ security:
6702
+ - BearerAuth: []
6703
+ parameters:
6704
+ - in: path
6705
+ name: connectionId
6706
+ required: true
6707
+ schema:
6708
+ type: string
6709
+ format: uuid
6710
+ responses:
6711
+ "200":
6712
+ description: Entitlement watches
6713
+ content:
6714
+ application/json:
6715
+ schema:
6716
+ $ref: "#/components/schemas/EntitlementsListResponse"
6717
+ "404":
6718
+ $ref: "#/components/responses/NotFound"
6719
+
6720
+ /v1/platform/connections/{connectionId}/entitlements/refresh:
6721
+ post:
6722
+ tags: [Platform]
6723
+ summary: Refresh entitlement evaluations
6724
+ description: Triggers an immediate entitlement monitor cycle for this connection's org.
6725
+ security:
6726
+ - BearerAuth: []
6727
+ parameters:
6728
+ - in: path
6729
+ name: connectionId
6730
+ required: true
6731
+ schema:
6732
+ type: string
6733
+ format: uuid
6734
+ responses:
6735
+ "202":
6736
+ description: Refresh accepted
6737
+ "404":
6738
+ $ref: "#/components/responses/NotFound"
6739
+
6128
6740
  /v1/platform/apps/{appId}/audit:
6129
6741
  get:
6130
6742
  tags: [Platform]
@@ -6945,9 +7557,10 @@ paths:
6945
7557
  tags: [Authentication]
6946
7558
  summary: Begin passkey transaction authorization
6947
7559
  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.
7560
+ Requires `tx_digest` — SHA-256 hex of the canonical digest for the
7561
+ treasury action being authorized (`send` or `swap`). The server
7562
+ recomputes this digest on send/swap and rejects passkey tokens that
7563
+ do not match.
6951
7564
  operationId: passkeyTxAssertBegin
6952
7565
  security:
6953
7566
  - BearerAuth: []
@@ -6956,17 +7569,20 @@ paths:
6956
7569
  content:
6957
7570
  application/json:
6958
7571
  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
7572
+ $ref: "#/components/schemas/PasskeyTxAssertBeginRequest"
6965
7573
  responses:
6966
7574
  "200":
6967
7575
  description: WebAuthn challenge
7576
+ content:
7577
+ application/json:
7578
+ schema:
7579
+ $ref: "#/components/schemas/PasskeyAssertBeginResponse"
6968
7580
  "400":
6969
- description: Missing or invalid tx_digest
7581
+ description: Missing or invalid tx_digest, or invalid action
7582
+ "403":
7583
+ $ref: "#/components/responses/Forbidden"
7584
+ "404":
7585
+ description: No passkeys registered for the user
6970
7586
 
6971
7587
  /v1/auth/passkeys/tx-assert/complete:
6972
7588
  post:
@@ -9731,6 +10347,59 @@ paths:
9731
10347
  "403":
9732
10348
  $ref: "#/components/responses/Forbidden"
9733
10349
 
10350
+ /v1/org/guardrail-shadow-report:
10351
+ get:
10352
+ tags: [Organization]
10353
+ summary: Get guardrail shadow divergence report
10354
+ description: |
10355
+ Returns Convention 6 shadow-mode violations (`guardrail_shadow.would_deny` audit events)
10356
+ grouped by reason code. Owner/admin only.
10357
+ operationId: getGuardrailShadowReport
10358
+ security:
10359
+ - BearerAuth: []
10360
+ parameters:
10361
+ - name: since
10362
+ in: query
10363
+ schema:
10364
+ type: string
10365
+ format: date-time
10366
+ - name: until
10367
+ in: query
10368
+ schema:
10369
+ type: string
10370
+ format: date-time
10371
+ responses:
10372
+ "200":
10373
+ description: Guardrail shadow report
10374
+ content:
10375
+ application/json:
10376
+ schema:
10377
+ $ref: "#/components/schemas/GuardrailShadowReportResponse"
10378
+ "401":
10379
+ $ref: "#/components/responses/Unauthorized"
10380
+ "403":
10381
+ $ref: "#/components/responses/Forbidden"
10382
+
10383
+ /v1/org/guardrail-revisions:
10384
+ get:
10385
+ tags: [Organization]
10386
+ summary: List guardrail revision history
10387
+ description: Audit trail of agent and binding guardrail changes. Owner/admin only.
10388
+ operationId: listGuardrailRevisions
10389
+ security:
10390
+ - BearerAuth: []
10391
+ responses:
10392
+ "200":
10393
+ description: Guardrail revisions
10394
+ content:
10395
+ application/json:
10396
+ schema:
10397
+ $ref: "#/components/schemas/GuardrailRevisionListResponse"
10398
+ "401":
10399
+ $ref: "#/components/responses/Unauthorized"
10400
+ "403":
10401
+ $ref: "#/components/responses/Forbidden"
10402
+
9734
10403
  # ---------------------------------------------------------------------------
9735
10404
  # Contract ABI Registry
9736
10405
  # ---------------------------------------------------------------------------
@@ -11092,6 +11761,10 @@ components:
11092
11761
  type: boolean
11093
11762
  mfa_token:
11094
11763
  type: string
11764
+ mfa_method:
11765
+ type: string
11766
+ enum: [totp, passkey]
11767
+ description: When MFA is required, which second factor to collect
11095
11768
 
11096
11769
  TokenResponse:
11097
11770
  type: object
@@ -11105,6 +11778,13 @@ components:
11105
11778
  type: integer
11106
11779
  refresh_token:
11107
11780
  type: string
11781
+ mfa_required:
11782
+ type: boolean
11783
+ mfa_token:
11784
+ type: string
11785
+ mfa_method:
11786
+ type: string
11787
+ enum: [totp, passkey]
11108
11788
 
11109
11789
  AgentTokenRequest:
11110
11790
  type: object
@@ -11260,6 +11940,12 @@ components:
11260
11940
  properties:
11261
11941
  enabled:
11262
11942
  type: boolean
11943
+ eligible:
11944
+ type: boolean
11945
+ totp_enabled:
11946
+ type: boolean
11947
+ passkey_mfa_enabled:
11948
+ type: boolean
11263
11949
 
11264
11950
  MfaSetupResponse:
11265
11951
  type: object
@@ -12016,7 +12702,9 @@ components:
12016
12702
  additionalProperties: true
12017
12703
  description: |
12018
12704
  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.
12705
+ Each value may include max_value, daily_limit, to_allowlist, token_allowlist, max_per_day,
12706
+ overhead_budget, max_ata_creates_per_day, max_fee_per_gas_gwei, max_gas_limit,
12707
+ gas_daily_budget_native (UTC-day cumulative EVM gas estimate in native units).
12020
12708
  Strictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.
12021
12709
  tx_max_per_day:
12022
12710
  type: integer
@@ -12330,7 +13018,8 @@ components:
12330
13018
  additionalProperties: true
12331
13019
  description: |
12332
13020
  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).
13021
+ Each value may include max_value, daily_limit, to_allowlist, token_allowlist (legacy *_eth keys accepted),
13022
+ max_fee_per_gas_gwei, max_gas_limit, gas_daily_budget_native (UTC-day cumulative EVM gas in native units).
12334
13023
  Strictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.
12335
13024
  api_key_expires_at:
12336
13025
  type: string
@@ -12351,6 +13040,17 @@ components:
12351
13040
  type: object
12352
13041
  additionalProperties: true
12353
13042
  description: Per-environment guardrail overrides keyed by environment slug.
13043
+ address_screening_policy:
13044
+ type: object
13045
+ additionalProperties: true
13046
+ description: Recipient address screening policy. `mode` may be `off`, `deny`, or `approve`.
13047
+ approval_id:
13048
+ type: string
13049
+ format: uuid
13050
+ description: >
13051
+ Approved policy_change id when applying a queued guardrail
13052
+ widening. Resubmit PATCH with this field after the approval
13053
+ has been approved via POST /v1/approvals/{approval_id}/decide.
12354
13054
 
12355
13055
  AgentResponse:
12356
13056
  type: object
@@ -12638,6 +13338,10 @@ components:
12638
13338
  type: object
12639
13339
  additionalProperties: true
12640
13340
  description: Per-environment guardrail overrides keyed by environment slug.
13341
+ address_screening_policy:
13342
+ type: object
13343
+ additionalProperties: true
13344
+ description: Recipient address screening policy. `mode` may be `off`, `deny`, or `approve`.
12641
13345
 
12642
13346
  KnownToken:
12643
13347
  type: object
@@ -15775,12 +16479,29 @@ components:
15775
16479
  subject_token_type:
15776
16480
  type: string
15777
16481
  default: "urn:ietf:params:oauth:token-type:jwt"
16482
+ description: |
16483
+ Token type for subject_token. Use `urn:1claw:params:oauth:token-type:siwe`
16484
+ with `siwe_message` and `siwe_signature` for wallet-based provisioning.
15778
16485
  email:
15779
16486
  type: string
15780
16487
  format: email
15781
16488
  description: Fallback when subject_token is not provided
15782
16489
  display_name:
15783
16490
  type: string
16491
+ siwe_message:
16492
+ type: string
16493
+ description: EIP-4361 Sign-In With Ethereum message (required for SIWE upsert)
16494
+ siwe_signature:
16495
+ type: string
16496
+ description: Hex-encoded SIWE signature (required for SIWE upsert)
16497
+ return_to:
16498
+ type: string
16499
+ format: uri
16500
+ description: Redirect URL after cross-org link consent
16501
+ create_sub_org:
16502
+ type: boolean
16503
+ default: false
16504
+ description: When true, creates a sub-org under the platform app's org
15784
16505
 
15785
16506
  PlatformUserResponse:
15786
16507
  type: object
@@ -15869,6 +16590,12 @@ components:
15869
16590
  type: string
15870
16591
  format: uri
15871
16592
  description: URL to redirect the user to after claiming resources.
16593
+ parameters:
16594
+ type: object
16595
+ additionalProperties: true
16596
+ description: |
16597
+ Template parameters substituted as `{{params.*}}` during bootstrap.
16598
+ Combined with `Idempotency-Key` header for params-aware idempotent replay.
15872
16599
 
15873
16600
  BootstrapResponse:
15874
16601
  type: object
@@ -16365,32 +17092,52 @@ components:
16365
17092
  format: date-time
16366
17093
  nullable: true
16367
17094
 
17095
+ GuardrailReasonCode:
17096
+ type: string
17097
+ description: |
17098
+ Stable snake_case reason codes for guardrail violations (Convention 1).
17099
+ Shadow-mode `"log"` emits the same codes in `guardrail_shadow.would_deny`
17100
+ audit events with `enforced: false`. 202 HITL responses use
17101
+ `approval_available: true` instead of a deny reason_code.
17102
+ enum:
17103
+ - binding_rpm_exceeded
17104
+ - agent_rpm_exceeded
17105
+ - graphql_mutation_blocked
17106
+ - graphql_depth_exceeded
17107
+ - graphql_parse_failed
17108
+ - graphql_introspection_blocked
17109
+ - response_too_large
17110
+ - request_too_large
17111
+ - method_not_allowed
17112
+ - header_not_allowed
17113
+ - dns_private_ip_blocked
17114
+ - agent_suspended
17115
+ - outside_time_window
17116
+ - secret_in_request
17117
+ - concurrency_exceeded
17118
+ - org_frozen
17119
+ - price_unavailable
17120
+ - gas_fee_exceeded
17121
+ - unlimited_approval_blocked
17122
+ - tx_per_recipient_limit_exceeded
17123
+ - tx_max_value_exceeded
17124
+ - tx_daily_limit_exceeded
17125
+ - delegation_signing_blocked
17126
+ - recipient_screening_failed
17127
+ - screening_provider_unavailable
17128
+ - human_factor_auth_required
17129
+ - register_passkey_required
17130
+
16368
17131
  GuardrailViolation:
16369
17132
  type: object
17133
+ description: Convention 1 machine-readable guardrail denial JSON body.
16370
17134
  required: [error, reason_code, approval_available]
16371
17135
  properties:
16372
17136
  error:
16373
17137
  type: string
16374
17138
  enum: [guardrail_violation]
16375
17139
  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
17140
+ $ref: "#/components/schemas/GuardrailReasonCode"
16394
17141
  limit:
16395
17142
  type: string
16396
17143
  nullable: true
@@ -16410,6 +17157,11 @@ components:
16410
17157
  type: string
16411
17158
  nullable: true
16412
17159
 
17160
+ GuardrailDenial:
17161
+ description: Alias of GuardrailViolation (Convention 1 JSON shape).
17162
+ allOf:
17163
+ - $ref: "#/components/schemas/GuardrailViolation"
17164
+
16413
17165
  # --- Email OTP ---
16414
17166
 
16415
17167
  EmailOtpVerifyResponse:
@@ -16532,33 +17284,234 @@ components:
16532
17284
  max_transactions_per_day:
16533
17285
  type: integer
16534
17286
  description: Maximum number of transactions per 24h window
17287
+ inference_allowance_usd:
17288
+ type: string
17289
+ description: Monthly LLM inference allowance in USD (decimal string)
17290
+ inference_reserved_pct:
17291
+ type: integer
17292
+ minimum: 0
17293
+ maximum: 100
17294
+ default: 25
17295
+ description: Percent of allowance held in reserve (not spendable)
17296
+ inference_hard_stop:
17297
+ type: boolean
17298
+ default: true
17299
+ description: When true, block inference when allowance is exhausted
17300
+ inference_allowance_mode:
17301
+ type: string
17302
+ enum: [policy, credits]
17303
+ default: policy
17304
+ max_request_cost_usd:
17305
+ type: string
17306
+ description: Maximum estimated cost per LLM request in USD
17307
+ human_factor_auth:
17308
+ type: object
17309
+ additionalProperties: true
17310
+ description: |
17311
+ Human factor auth requirements for send/swap/export.
17312
+ Fields: send, swap, export (password_or_passkey | passkey_only | passkey_required | password_only | reauth_token_only),
17313
+ conditional.require_passkey_above_usd, conditional.require_passkey_for_new_recipient.
16535
17314
 
16536
- SpendPolicyResponse:
17315
+ SiweChallengeRequest:
16537
17316
  type: object
16538
- required: [id, platform_app_id, created_at]
16539
17317
  properties:
16540
- id:
17318
+ domain:
16541
17319
  type: string
16542
- format: uuid
16543
- platform_app_id:
17320
+ description: Optional SIWE domain override (defaults to platform app's siwe_domain)
17321
+
17322
+ SiweChallengeResponse:
17323
+ type: object
17324
+ required: [nonce, expires_in, domain]
17325
+ properties:
17326
+ nonce:
17327
+ type: string
17328
+ expires_in:
17329
+ type: integer
17330
+ description: Seconds until nonce expiry
17331
+ domain:
17332
+ type: string
17333
+
17334
+ ConnectionDetailResponse:
17335
+ type: object
17336
+ required: [connection_id, user_id, status, entitlement_status, vault_ids, agent_ids, claim]
17337
+ properties:
17338
+ connection_id:
16544
17339
  type: string
16545
17340
  format: uuid
16546
17341
  user_id:
16547
17342
  type: string
16548
17343
  format: uuid
16549
- nullable: true
16550
- to_allowlist:
16551
- type: array
16552
- items: { type: string }
16553
- to_denylist:
16554
- type: array
16555
- items: { type: string }
16556
- max_value_per_tx_eth:
17344
+ status:
16557
17345
  type: string
16558
- nullable: true
16559
- daily_limit_eth:
17346
+ entitlement_status:
16560
17347
  type: string
16561
- nullable: true
17348
+ wallet_address:
17349
+ type: string
17350
+ nullable: true
17351
+ vault_ids:
17352
+ type: array
17353
+ items:
17354
+ type: string
17355
+ format: uuid
17356
+ agent_ids:
17357
+ type: array
17358
+ items:
17359
+ type: string
17360
+ format: uuid
17361
+ claimed_at:
17362
+ type: string
17363
+ format: date-time
17364
+ nullable: true
17365
+ claim:
17366
+ $ref: "#/components/schemas/ClaimStatusResponse"
17367
+
17368
+ ClaimStatusResponse:
17369
+ type: object
17370
+ required: [status]
17371
+ properties:
17372
+ status:
17373
+ type: string
17374
+ enum: [pending, active, claimed]
17375
+ redeemed_at:
17376
+ type: string
17377
+ format: date-time
17378
+ nullable: true
17379
+
17380
+ ConnectionUsageResponse:
17381
+ type: object
17382
+ required: [connection_id, period, inference_spent_usd]
17383
+ properties:
17384
+ connection_id:
17385
+ type: string
17386
+ format: uuid
17387
+ period:
17388
+ type: string
17389
+ description: UTC month (YYYY-MM)
17390
+ inference_spent_usd:
17391
+ type: string
17392
+
17393
+ EntitlementsListResponse:
17394
+ type: object
17395
+ required: [evaluations]
17396
+ properties:
17397
+ evaluations:
17398
+ type: array
17399
+ items:
17400
+ $ref: "#/components/schemas/EntitlementEvaluationResponse"
17401
+
17402
+ EntitlementEvaluationResponse:
17403
+ type: object
17404
+ required: [id, status, watch_kind, chain, holder_address]
17405
+ properties:
17406
+ id:
17407
+ type: string
17408
+ status:
17409
+ type: string
17410
+ watch_kind:
17411
+ type: string
17412
+ chain:
17413
+ type: string
17414
+ holder_address:
17415
+ type: string
17416
+ last_value_raw:
17417
+ type: string
17418
+ nullable: true
17419
+ last_checked_at:
17420
+ type: string
17421
+ format: date-time
17422
+ nullable: true
17423
+
17424
+ TemplatePreviewRequest:
17425
+ type: object
17426
+ properties:
17427
+ parameters:
17428
+ type: object
17429
+ additionalProperties: true
17430
+ subject:
17431
+ type: object
17432
+ properties:
17433
+ user_id:
17434
+ type: string
17435
+ external_subject:
17436
+ type: string
17437
+ wallet_address:
17438
+ type: string
17439
+ email:
17440
+ type: string
17441
+
17442
+ TemplatePreviewResponse:
17443
+ type: object
17444
+ required: [resolved_spec]
17445
+ properties:
17446
+ resolved_spec:
17447
+ type: object
17448
+ additionalProperties: true
17449
+
17450
+ InferenceBudgetResponse:
17451
+ type: object
17452
+ required:
17453
+ - allowance_usd
17454
+ - spent_usd
17455
+ - remaining_usd
17456
+ - reserved_pct
17457
+ - max_request_cost_usd
17458
+ - period_end
17459
+ properties:
17460
+ allowance_usd:
17461
+ type: string
17462
+ spent_usd:
17463
+ type: string
17464
+ remaining_usd:
17465
+ type: string
17466
+ reserved_pct:
17467
+ type: integer
17468
+ max_request_cost_usd:
17469
+ type: string
17470
+ period_end:
17471
+ type: string
17472
+ format: date-time
17473
+ connection_id:
17474
+ type: string
17475
+ format: uuid
17476
+ nullable: true
17477
+
17478
+ InferenceBudgetUnconfiguredResponse:
17479
+ type: object
17480
+ properties:
17481
+ allowance_usd:
17482
+ type: string
17483
+ nullable: true
17484
+ remaining_usd:
17485
+ nullable: true
17486
+ message:
17487
+ type: string
17488
+
17489
+ SpendPolicyResponse:
17490
+ type: object
17491
+ required: [id, platform_app_id, created_at]
17492
+ properties:
17493
+ id:
17494
+ type: string
17495
+ format: uuid
17496
+ platform_app_id:
17497
+ type: string
17498
+ format: uuid
17499
+ user_id:
17500
+ type: string
17501
+ format: uuid
17502
+ nullable: true
17503
+ to_allowlist:
17504
+ type: array
17505
+ items: { type: string }
17506
+ to_denylist:
17507
+ type: array
17508
+ items: { type: string }
17509
+ max_value_per_tx_eth:
17510
+ type: string
17511
+ nullable: true
17512
+ daily_limit_eth:
17513
+ type: string
17514
+ nullable: true
16562
17515
  allowed_chains:
16563
17516
  type: array
16564
17517
  items: { type: string }
@@ -16568,12 +17521,159 @@ components:
16568
17521
  max_transactions_per_day:
16569
17522
  type: integer
16570
17523
  nullable: true
17524
+ inference_allowance_usd:
17525
+ type: string
17526
+ nullable: true
17527
+ inference_reserved_pct:
17528
+ type: integer
17529
+ nullable: true
17530
+ inference_hard_stop:
17531
+ type: boolean
17532
+ nullable: true
17533
+ inference_allowance_mode:
17534
+ type: string
17535
+ nullable: true
17536
+ max_request_cost_usd:
17537
+ type: string
17538
+ nullable: true
17539
+ human_factor_auth:
17540
+ type: object
17541
+ additionalProperties: true
17542
+ nullable: true
16571
17543
  created_at:
16572
17544
  type: string
16573
17545
  format: date-time
16574
17546
 
16575
17547
  # --- Risk Engine ---
16576
17548
 
17549
+ HumanFactorAuthPolicy:
17550
+ type: object
17551
+ properties:
17552
+ send:
17553
+ type: string
17554
+ enum: [password_or_passkey, passkey_only, passkey_required, password_only, reauth_token_only]
17555
+ swap:
17556
+ type: string
17557
+ enum: [password_or_passkey, passkey_only, passkey_required, password_only, reauth_token_only]
17558
+ export:
17559
+ type: string
17560
+ enum: [password_or_passkey, passkey_only, passkey_required, password_only, reauth_token_only]
17561
+ conditional:
17562
+ type: object
17563
+ properties:
17564
+ require_passkey_above_usd:
17565
+ type: string
17566
+ nullable: true
17567
+ require_passkey_for_new_recipient:
17568
+ type: boolean
17569
+
17570
+ UpsertHumanFactorAuthRequest:
17571
+ type: object
17572
+ required: [policy]
17573
+ properties:
17574
+ policy:
17575
+ $ref: "#/components/schemas/HumanFactorAuthPolicy"
17576
+
17577
+ HumanFactorAuthResponse:
17578
+ type: object
17579
+ required: [policy, source]
17580
+ properties:
17581
+ policy:
17582
+ $ref: "#/components/schemas/HumanFactorAuthPolicy"
17583
+ source:
17584
+ type: string
17585
+ description: user | platform_app | spend_policy | default
17586
+
17587
+ TreasuryAuthPolicyResponse:
17588
+ type: object
17589
+ required: [policy, source, registered_passkeys]
17590
+ properties:
17591
+ policy:
17592
+ $ref: "#/components/schemas/HumanFactorAuthPolicy"
17593
+ source:
17594
+ type: string
17595
+ description: user | platform_app | spend_policy | default
17596
+ registered_passkeys:
17597
+ type: integer
17598
+ minimum: 0
17599
+ description: Number of WebAuthn passkeys registered for the calling user.
17600
+
17601
+ PasskeyTxAssertBeginRequest:
17602
+ type: object
17603
+ required: [tx_digest]
17604
+ properties:
17605
+ tx_digest:
17606
+ type: string
17607
+ description: 64-char hex SHA-256 of canonical send or swap params
17608
+ action:
17609
+ type: string
17610
+ enum: [send, swap]
17611
+ default: send
17612
+ description: Treasury action being authorized. Defaults to `send`.
17613
+
17614
+ PasskeyAssertBeginResponse:
17615
+ type: object
17616
+ required: [challenge, rp_id, timeout, user_verification, allow_credentials]
17617
+ properties:
17618
+ challenge:
17619
+ type: string
17620
+ rp_id:
17621
+ type: string
17622
+ timeout:
17623
+ type: integer
17624
+ user_verification:
17625
+ type: string
17626
+ allow_credentials:
17627
+ type: array
17628
+ items:
17629
+ $ref: "#/components/schemas/AllowCredential"
17630
+
17631
+ AllowCredential:
17632
+ type: object
17633
+ required: [id, type]
17634
+ properties:
17635
+ id:
17636
+ type: string
17637
+ type:
17638
+ type: string
17639
+ enum: [public-key]
17640
+ transports:
17641
+ type: array
17642
+ items:
17643
+ type: string
17644
+
17645
+ MfaPasskeyCompleteRequest:
17646
+ type: object
17647
+ required: [mfa_token, credential_id, authenticator_data, client_data_json, signature]
17648
+ properties:
17649
+ mfa_token:
17650
+ type: string
17651
+ credential_id:
17652
+ type: string
17653
+ authenticator_data:
17654
+ type: string
17655
+ client_data_json:
17656
+ type: string
17657
+ signature:
17658
+ type: string
17659
+
17660
+ GuardrailWideningQueuedResponse:
17661
+ type: object
17662
+ required: [status, approval_id, revision_id, message]
17663
+ properties:
17664
+ status:
17665
+ type: string
17666
+ enum: [awaiting_approval]
17667
+ approval_id:
17668
+ type: string
17669
+ format: uuid
17670
+ revision_id:
17671
+ type: string
17672
+ format: uuid
17673
+ message:
17674
+ type: string
17675
+ description: Human-readable explanation of the queued change.
17676
+
16577
17677
  RiskEvent:
16578
17678
  type: object
16579
17679
  required: [id, occurred_at, principal_type, principal_id, org_id, event_type, payload, created_at]
@@ -16810,6 +17910,13 @@ components:
16810
17910
  description: "Legacy: inline credential value."
16811
17911
  credential_source:
16812
17912
  $ref: "#/components/schemas/CredentialSource"
17913
+ approval_id:
17914
+ type: string
17915
+ format: uuid
17916
+ description: >
17917
+ Approved policy_change id when applying a queued binding
17918
+ guardrail widening. Resubmit PATCH with this field after
17919
+ approval via POST /v1/approvals/{approval_id}/decide.
16813
17920
 
16814
17921
  BindingGuardrails:
16815
17922
  type: object
@@ -18525,6 +19632,269 @@ components:
18525
19632
  type: string
18526
19633
  format: date-time
18527
19634
 
19635
+ GuardrailShadowReportResponse:
19636
+ type: object
19637
+ properties:
19638
+ org_id:
19639
+ type: string
19640
+ format: uuid
19641
+ since:
19642
+ type: string
19643
+ format: date-time
19644
+ until:
19645
+ type: string
19646
+ format: date-time
19647
+ total_would_deny:
19648
+ type: integer
19649
+ format: int64
19650
+ by_reason:
19651
+ type: array
19652
+ items:
19653
+ $ref: "#/components/schemas/GuardrailShadowReasonRow"
19654
+
19655
+ GuardrailShadowReasonRow:
19656
+ type: object
19657
+ properties:
19658
+ reason_code:
19659
+ type: string
19660
+ would_deny_count:
19661
+ type: integer
19662
+ format: int64
19663
+ enforced_count:
19664
+ type: integer
19665
+ format: int64
19666
+
19667
+ GuardrailRevisionListResponse:
19668
+ type: object
19669
+ properties:
19670
+ revisions:
19671
+ type: array
19672
+ items:
19673
+ $ref: "#/components/schemas/GuardrailRevisionRow"
19674
+
19675
+ GuardrailRevisionRow:
19676
+ type: object
19677
+ properties:
19678
+ id:
19679
+ type: string
19680
+ format: uuid
19681
+ org_id:
19682
+ type: string
19683
+ format: uuid
19684
+ resource_type:
19685
+ type: string
19686
+ enum: [agent, binding]
19687
+ resource_id:
19688
+ type: string
19689
+ format: uuid
19690
+ actor_id:
19691
+ type: string
19692
+ format: uuid
19693
+ before_json:
19694
+ type: object
19695
+ additionalProperties: true
19696
+ after_json:
19697
+ type: object
19698
+ additionalProperties: true
19699
+ change_kind:
19700
+ type: string
19701
+ enum: [narrowing, widening, neutral]
19702
+ approval_id:
19703
+ type: string
19704
+ format: uuid
19705
+ nullable: true
19706
+ created_at:
19707
+ type: string
19708
+ format: date-time
19709
+
19710
+ GuardrailReplayRequest:
19711
+ type: object
19712
+ properties:
19713
+ days:
19714
+ type: integer
19715
+ minimum: 1
19716
+ maximum: 90
19717
+ draft_guardrails:
19718
+ type: object
19719
+ additionalProperties: true
19720
+ draft_approval_policy:
19721
+ type: object
19722
+ additionalProperties: true
19723
+
19724
+ GuardrailReplayResponse:
19725
+ type: object
19726
+ properties:
19727
+ agent_id:
19728
+ type: string
19729
+ format: uuid
19730
+ window_days:
19731
+ type: integer
19732
+ format: int64
19733
+ allowed:
19734
+ type: integer
19735
+ format: int64
19736
+ denied:
19737
+ type: integer
19738
+ format: int64
19739
+ would_require_approval:
19740
+ type: integer
19741
+ format: int64
19742
+ samples:
19743
+ type: array
19744
+ items:
19745
+ type: object
19746
+ additionalProperties: true
19747
+
19748
+ AgentAccountListResponse:
19749
+ type: object
19750
+ properties:
19751
+ accounts:
19752
+ type: array
19753
+ items:
19754
+ $ref: "#/components/schemas/AgentAccountResponse"
19755
+
19756
+ AgentAccountResponse:
19757
+ type: object
19758
+ properties:
19759
+ id:
19760
+ type: string
19761
+ format: uuid
19762
+ org_id:
19763
+ type: string
19764
+ format: uuid
19765
+ agent_id:
19766
+ type: string
19767
+ format: uuid
19768
+ chain:
19769
+ type: string
19770
+ account_type:
19771
+ type: string
19772
+ address:
19773
+ type: string
19774
+ safe_version:
19775
+ type: string
19776
+ modules_enabled:
19777
+ type: array
19778
+ items:
19779
+ type: string
19780
+ deploy_status:
19781
+ type: string
19782
+ cosign_enabled:
19783
+ type: boolean
19784
+ metadata:
19785
+ type: object
19786
+ created_at:
19787
+ type: string
19788
+ format: date-time
19789
+ updated_at:
19790
+ type: string
19791
+ format: date-time
19792
+
19793
+ MigrationPlanResponse:
19794
+ type: object
19795
+ properties:
19796
+ agent_id:
19797
+ type: string
19798
+ format: uuid
19799
+ chain:
19800
+ type: string
19801
+ safe_address:
19802
+ type: string
19803
+ safe_version:
19804
+ type: string
19805
+ modules:
19806
+ type: array
19807
+ items:
19808
+ type: string
19809
+ eoa_address:
19810
+ type: string
19811
+ sweep_instructions:
19812
+ type: array
19813
+ items:
19814
+ type: object
19815
+ properties:
19816
+ asset:
19817
+ type: string
19818
+ action:
19819
+ type: string
19820
+ note:
19821
+ type: string
19822
+ roles_config_hash:
19823
+ type: string
19824
+ allowance_config_hash:
19825
+ type: string
19826
+ warnings:
19827
+ type: array
19828
+ items:
19829
+ type: string
19830
+ deploy_status:
19831
+ type: string
19832
+
19833
+ ProvisionAgentAccountRequest:
19834
+ type: object
19835
+ required: [chain]
19836
+ properties:
19837
+ chain:
19838
+ type: string
19839
+ account_type:
19840
+ type: string
19841
+ default: eoa
19842
+ address:
19843
+ type: string
19844
+
19845
+ SafeModuleRegistryResponse:
19846
+ type: object
19847
+ properties:
19848
+ chain:
19849
+ type: string
19850
+ modules:
19851
+ type: array
19852
+ items:
19853
+ $ref: "#/components/schemas/SafeModuleInfo"
19854
+
19855
+ SafeModuleInfo:
19856
+ type: object
19857
+ properties:
19858
+ name:
19859
+ type: string
19860
+ address:
19861
+ type: string
19862
+ version:
19863
+ type: string
19864
+
19865
+ AllowanceReconcileReport:
19866
+ type: object
19867
+ properties:
19868
+ org_id:
19869
+ type: string
19870
+ format: uuid
19871
+ agents_checked:
19872
+ type: integer
19873
+ compiled:
19874
+ type: array
19875
+ items:
19876
+ type: object
19877
+ additionalProperties: true
19878
+ drift_detected:
19879
+ type: array
19880
+ items:
19881
+ type: object
19882
+ additionalProperties: true
19883
+ onchain_sync:
19884
+ type: string
19885
+ description: counterfactual when on-chain broadcast is stubbed pre-audit
19886
+
19887
+ NotImplementedResponse:
19888
+ type: object
19889
+ required: [error, phase, message]
19890
+ properties:
19891
+ error:
19892
+ type: string
19893
+ phase:
19894
+ type: string
19895
+ message:
19896
+ type: string
19897
+
18528
19898
  # -------------------------------------------------------------------
18529
19899
  # Contract ABIs
18530
19900
  # -------------------------------------------------------------------