openapi.yaml

openapi: 3.1.0

info:
    title: 1Claw API
    version: 2.27.0
    description: |
        Secure secret management for AI agents. Provides vaults, secrets,
        policy-based access control, agent identity, Intents API,
        sharing, billing, and audit logging.

        All endpoints require JWT Bearer authentication unless marked with
        `security: []`.
    contact:
        email: ops@1claw.xyz

servers:
    - url: http://localhost:8443
      description: Development
    - url: https://api.1claw.xyz
      description: Production
    - url: https://shroud.1claw.xyz
      description: Shroud TEE Proxy (Intents API + LLM proxy)

x-agentcash-guidance:
    llmsTxtUrl: https://1claw.xyz/llms.txt

security:
    - BearerAuth: []

tags:
    - name: Authentication
      description: Credential exchange, MFA, device auth, token management
    - name: API Keys
      description: Personal API key management
    - name: Vaults
      description: Vault lifecycle operations
    - name: Secrets
      description: Secret CRUD within vaults
    - name: Policies
      description: Access policy management
    - name: Agents
      description: Agent identity and key management
    - name: Transactions
      description: Intents API (signing, simulation)
    - name: Chains
      description: Blockchain chain registry
    - name: Sharing
      description: Secret sharing links
    - name: Organization
      description: Org membership and roles
    - name: Billing
      description: Subscriptions, credits, and usage
    - name: Audit
      description: Immutable audit event log
    - name: Security
      description: IP rules and security configuration
    - name: Treasury
      description: Multi-sig treasury wallets (Safe) and agent access requests
    - name: Treasury Wallets
      description: Multi-chain wallet generation for human users (replaces CDP embedded wallets)
    - name: Admin
      description: Platform administration
    - name: Health
      description: Service health checks
    - name: Approvals
      description: Human-in-the-loop approval workflow for agent actions
    - name: Signing Keys
      description: Per-agent multi-chain signing key management
    - name: Webhooks
      description: Event webhook registration and management
    - name: Platform
      description: Platform API for developers building on 1Claw (plt_ keys, user provisioning, bootstrap templates)
    - name: OAuth
      description: OAuth 2.0 authorization server (PKCE, consent, token exchange, OIDC UserInfo)
    - name: Risk Engine
      description: Risk events, verdicts, and honeytoken management
    - name: Tokens
      description: Known token registry for guardrail enforcement
    - name: Execution Intents
      description: Execute HTTP calls, queries, and more through pre-configured bindings
    - name: Payment Cards
      description: Order prepaid/gift cards via x402, then reveal, refresh, and void them

# =============================================================================
# PATHS
# =============================================================================

paths:
    # ---------------------------------------------------------------------------
    # Authentication
    # ---------------------------------------------------------------------------

    /v1/auth/token:
        post:
            tags: [Authentication]
            summary: Login with email and password
            operationId: login
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/LoginRequest"
            responses:
                "200":
                    description: Authenticated (or MFA required)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/LoginResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"
        delete:
            tags: [Authentication]
            summary: Revoke current token
            operationId: revokeToken
            responses:
                "204":
                    description: Token revoked
                "401":
                    $ref: "#/components/responses/Unauthorized"

    /v1/auth/agent-token:
        post:
            tags: [Authentication]
            summary: Exchange agent credentials for JWT
            description: |
                Returns a short-lived EdDSA-signed JWT (`access_token`). Standard claims include `sub`
                (`agent:<uuid>`), `org`, `scopes`, `vault_ids`, optional `intents_api_enabled`, optional
                `shroud_enabled`, optional `llm_token_billing` / `stripe_customer_id` when org LLM billing is on.

                When **`shroud_enabled`** is true, the JWT payload may include **`shroud_config`**: a JSON object
                mirroring the agent row in Vault (same shape as `ShroudConfig` on `GET /v1/agents/{id}`).
                **Shroud** (TEE proxy) decodes this on each LLM request and runs **PolicyEngine** after the
                global inspection pipeline so per-agent limits and threat **block** actions apply without a
                separate policy fetch. Re-exchange the agent token after changing `shroud_config` so the JWT
                is fresh.

                User JWTs from password, API key, or device flow do **not** include `shroud_config`.
            operationId: agentToken
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/AgentTokenRequest"
            responses:
                "200":
                    description: Agent JWT issued
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TokenResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"

    /v1/auth/api-key-token:
        post:
            tags: [Authentication]
            summary: Exchange user API key for JWT
            operationId: apiKeyToken
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UserApiKeyTokenRequest"
            responses:
                "200":
                    description: JWT issued
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TokenResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"

    /v1/auth/refresh:
        post:
            tags: [Authentication]
            summary: Refresh an expiring JWT
            operationId: refreshToken
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [refresh_token]
                            properties:
                                refresh_token:
                                    type: string
            responses:
                "200":
                    description: Token refreshed
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TokenResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"

    /v1/auth/jwt-public-key:
        get:
            tags: [Authentication]
            summary: Get JWT verification public key
            description: |
                Returns the Ed25519 public key used to sign JWTs.
                Use this to verify tokens independently (e.g. in a TEE proxy or
                gateway). No authentication required.

                For OIDC-compliant relying parties (Anthropic Workload Identity
                Federation, etc.) prefer the JWKS endpoint at
                `/.well-known/jwks.json` together with the discovery document
                at `/.well-known/openid-configuration` — those advertise both
                Ed25519 and RS256 keys keyed by `kid` and survive key rotation.
            operationId: getJwtPublicKey
            security: []
            responses:
                "200":
                    description: JWT public key
                    content:
                        application/json:
                            schema:
                                type: object
                                required: [alg, public_key_base64]
                                properties:
                                    alg:
                                        type: string
                                        example: EdDSA
                                    public_key_base64:
                                        type: string
                                        description: Base64-encoded Ed25519 public key

    /v1/auth/federated-token:
        post:
            tags: [Authentication]
            summary: Exchange a 1claw token for an OIDC federation token (RFC 8693)
            description: |
                Mints a short-lived RS256-signed JWT targeted at an external
                relying party (e.g. Anthropic Workload Identity Federation).
                The relying party validates the token via this issuer's JWKS
                URL (`/.well-known/jwks.json`) and exchanges it for its own
                short-lived service credentials.

                Requirements:
                - The agent that owns the `subject_token` must have
                  `federation_enabled = true` and the requested `audience`
                  must appear in `federation_audiences`.
                - The `subject_token` must be a valid 1claw agent JWT or
                  `ocv_` API key.
                - Optional `scope` narrows the agent's existing scopes — it
                  cannot escalate.

                Returns 503 when `ONECLAW_JWT_RS256_SIGNING_KEY_ID` is not
                configured on the server.
            operationId: exchangeFederatedToken
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/TokenExchangeRequest"
                    application/x-www-form-urlencoded:
                        schema:
                            $ref: "#/components/schemas/TokenExchangeRequest"
            responses:
                "200":
                    description: Federation token issued
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TokenExchangeResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "503":
                    description: RS256 signing key not configured

    /.well-known/openid-configuration:
        get:
            tags: [Authentication]
            summary: OIDC discovery document
            description: |
                Standard OpenID Connect discovery document advertising the
                issuer URL, JWKS URL, supported algorithms (`EdDSA`, `RS256`),
                and the RFC 8693 token-exchange endpoint. External IdPs
                (Anthropic WIF, Okta, Auth0, etc.) read this URL to learn
                where 1claw publishes its JWKS.
            operationId: openidConfiguration
            security: []
            responses:
                "200":
                    description: Discovery document
                    content:
                        application/json:
                            schema:
                                type: object

    /.well-known/jwks.json:
        get:
            tags: [Authentication]
            summary: JSON Web Key Set
            description: |
                Public keys for every active version of every JWT signing
                key (Ed25519 + RSA-2048). Each entry includes a `kid` so
                consumers can validate tokens issued before the most recent
                key rotation. Cached for 5 minutes via `Cache-Control` and
                CORS-permissive for browser-based IdP consoles.
            operationId: jwks
            security: []
            responses:
                "200":
                    description: JWK Set
                    content:
                        application/jwk-set+json:
                            schema:
                                type: object
                                properties:
                                    keys:
                                        type: array
                                        items:
                                            type: object

    /v1/auth/signup:
        post:
            tags: [Authentication]
            summary: Create a new account
            operationId: signup
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/SignupRequest"
            responses:
                "200":
                    description: Account created (pending verification or auto-login)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SignupResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"

    /v1/auth/verify-email:
        post:
            tags: [Authentication]
            summary: Verify email address
            operationId: verifyEmail
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [token]
                            properties:
                                token:
                                    type: string
            responses:
                "200":
                    description: Email verified
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TokenResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"

    /v1/auth/forgot-password:
        post:
            tags: [Authentication]
            summary: Request password reset email
            description: |
                Always returns the same message whether or not the email exists (no account enumeration).
                Only password-based accounts receive mail.
            operationId: forgotPassword
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/ForgotPasswordRequest"
            responses:
                "200":
                    description: Acknowledgement (check email if account exists)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ForgotPasswordResponse"

    /v1/auth/reset-password:
        post:
            tags: [Authentication]
            summary: Set a new password using reset token from email
            operationId: resetPassword
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/ResetPasswordRequest"
            responses:
                "200":
                    description: Password updated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ResetPasswordResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"

    /v1/auth/google:
        post:
            tags: [Authentication]
            summary: Authenticate with Google OAuth
            operationId: googleAuth
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/GoogleAuthRequest"
            responses:
                "200":
                    description: Authenticated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TokenResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"

    /v1/auth/change-password:
        post:
            tags: [Authentication]
            summary: Change current user's password
            operationId: changePassword
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/ChangePasswordRequest"
            responses:
                "204":
                    description: Password changed
                "400":
                    $ref: "#/components/responses/BadRequest"

    /v1/auth/set-password:
        post:
            tags: [Authentication]
            summary: Set initial password for platform users
            description: Only allowed when the user has no password set (platform_oidc users after claiming).
            operationId: setPassword
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [password, password_confirm]
                            properties:
                                password:
                                    type: string
                                    minLength: 12
                                password_confirm:
                                    type: string
            responses:
                "200":
                    description: Password set successfully
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
                "400":
                    $ref: "#/components/responses/BadRequest"

    /v1/auth/change-email:
        post:
            tags: [Authentication]
            summary: Request email change
            description: Sends a 6-digit verification code to the new email address. Code expires in 10 minutes.
            operationId: changeEmail
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [new_email]
                            properties:
                                new_email:
                                    type: string
                                    format: email
            responses:
                "200":
                    description: Verification code sent
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
                                    new_email:
                                        type: string
                                    expires_in_seconds:
                                        type: integer
                "400":
                    $ref: "#/components/responses/BadRequest"
                "409":
                    description: Email already in use

    /v1/auth/verify-email-change:
        post:
            tags: [Authentication]
            summary: Verify email change with code
            operationId: verifyEmailChange
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [code]
                            properties:
                                code:
                                    type: string
            responses:
                "200":
                    description: Email updated
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
                                    email:
                                        type: string
                "400":
                    $ref: "#/components/responses/BadRequest"

    /v1/auth/passkeys/register/begin:
        post:
            tags: [Authentication]
            summary: Begin passkey registration
            description: Returns a WebAuthn challenge for creating a new passkey credential.
            operationId: passkeyRegisterBegin
            responses:
                "200":
                    description: Registration options
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    challenge:
                                        type: string
                                    rp_id:
                                        type: string
                                    rp_name:
                                        type: string
                                    user_id:
                                        type: string
                                    user_name:
                                        type: string
                                    user_display_name:
                                        type: string
                                    attestation:
                                        type: string
                                    authenticator_selection:
                                        type: object

    /v1/auth/passkeys/register/complete:
        post:
            tags: [Authentication]
            summary: Complete passkey registration
            operationId: passkeyRegisterComplete
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [credential_id, attestation_object, client_data_json]
                            properties:
                                credential_id:
                                    type: string
                                attestation_object:
                                    type: string
                                client_data_json:
                                    type: string
                                transports:
                                    type: array
                                    items:
                                        type: string
                                name:
                                    type: string
            responses:
                "201":
                    description: Passkey registered
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    passkey_id:
                                        type: string
                                        format: uuid
                                    credential_id:
                                        type: string

    /v1/auth/passkeys/assert/begin:
        post:
            tags: [Authentication]
            summary: Begin passkey authentication
            operationId: passkeyAssertBegin
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                email:
                                    type: string
                                    format: email
            responses:
                "200":
                    description: Assertion options
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    challenge:
                                        type: string
                                    rp_id:
                                        type: string
                                    timeout:
                                        type: integer
                                    user_verification:
                                        type: string
                                    allow_credentials:
                                        type: array
                                        items:
                                            type: object

    /v1/auth/passkeys/assert/complete:
        post:
            tags: [Authentication]
            summary: Complete passkey authentication
            operationId: passkeyAssertComplete
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [credential_id, authenticator_data, client_data_json, signature]
                            properties:
                                credential_id:
                                    type: string
                                authenticator_data:
                                    type: string
                                client_data_json:
                                    type: string
                                signature:
                                    type: string
            responses:
                "200":
                    description: Authentication successful
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    token:
                                        type: string
                                    refresh_token:
                                        type: string
                                    user:
                                        type: object

    /v1/auth/passkeys:
        get:
            tags: [Authentication]
            summary: List registered passkeys
            operationId: listPasskeys
            responses:
                "200":
                    description: List of passkeys
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    passkeys:
                                        type: array
                                        items:
                                            type: object
                                            properties:
                                                id:
                                                    type: string
                                                    format: uuid
                                                credential_id:
                                                    type: string
                                                name:
                                                    type: string
                                                last_used_at:
                                                    type: string
                                                created_at:
                                                    type: string

    /v1/auth/passkeys/{passkey_id}:
        delete:
            tags: [Authentication]
            summary: Delete a passkey
            operationId: deletePasskey
            parameters:
                - name: passkey_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Passkey deleted

    /v1/approvals/request:
        post:
            tags: [Approvals]
            summary: Request human approval (agent-only)
            description: Agents can request policy changes or other sensitive actions that require human approval.
            operationId: requestApproval
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [action, target_type, target_id, summary]
                            properties:
                                action:
                                    type: string
                                    description: "Type of action (e.g. policy_change)"
                                target_type:
                                    type: string
                                target_id:
                                    type: string
                                summary:
                                    type: object
                                    description: "JSON payload describing the request"
                                reason:
                                    type: string
                                risk_tier:
                                    type: integer
                                    minimum: 1
                                    maximum: 5
            responses:
                "202":
                    description: Approval request created
                    headers:
                        Location:
                            description: URL to poll for approval status
                            schema:
                                type: string
                                example: /v1/approvals/{id}
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ApprovalResponse"
                "403":
                    $ref: "#/components/responses/Forbidden"

    /v1/auth/me:
        get:
            tags: [Authentication]
            summary: Get current user profile
            operationId: getMe
            responses:
                "200":
                    description: User profile
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/UserProfileResponse"
        patch:
            tags: [Authentication]
            summary: Update user profile
            operationId: updateMe
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UpdateProfileRequest"
            responses:
                "200":
                    description: Profile updated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/UserProfileResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
        delete:
            tags: [Authentication]
            summary: Delete current user account
            operationId: deleteMe
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [confirmation]
                            properties:
                                confirmation:
                                    type: string
                                    description: Must be "DELETE MY ACCOUNT"
            responses:
                "204":
                    description: Account deleted
                "400":
                    $ref: "#/components/responses/BadRequest"

    # MFA

    /v1/auth/mfa/status:
        get:
            tags: [Authentication]
            summary: Check MFA enrollment status
            operationId: mfaStatus
            responses:
                "200":
                    description: MFA status
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/MfaStatusResponse"

    /v1/auth/mfa/setup:
        post:
            tags: [Authentication]
            summary: Begin MFA enrollment
            operationId: mfaSetup
            responses:
                "200":
                    description: TOTP setup details
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/MfaSetupResponse"

    /v1/auth/mfa/verify-setup:
        post:
            tags: [Authentication]
            summary: Confirm MFA enrollment with a TOTP code
            operationId: mfaVerifySetup
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/MfaVerifySetupRequest"
            responses:
                "200":
                    description: MFA enabled, recovery codes returned
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/MfaVerifySetupResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"

    /v1/auth/mfa/verify:
        post:
            tags: [Authentication]
            summary: Verify MFA code during login
            operationId: mfaVerify
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/MfaVerifyRequest"
            responses:
                "200":
                    description: MFA verified, JWT issued
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TokenResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"

    /v1/auth/mfa:
        delete:
            tags: [Authentication]
            summary: Disable MFA
            operationId: mfaDisable
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/MfaDisableRequest"
            responses:
                "204":
                    description: MFA disabled
                "400":
                    $ref: "#/components/responses/BadRequest"

    # Device Auth (CLI)

    /v1/auth/device/code:
        post:
            tags: [Authentication]
            summary: Request a device authorization code
            operationId: deviceCode
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/DeviceCodeRequest"
            responses:
                "200":
                    description: Device code issued
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/DeviceCodeResponse"

    /v1/auth/device/token:
        post:
            tags: [Authentication]
            summary: Poll for device authorization token
            operationId: deviceToken
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/DeviceTokenRequest"
            responses:
                "200":
                    description: Token issued or authorization pending
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/DeviceTokenResponse"

    /v1/auth/device/code/{user_code}:
        get:
            tags: [Authentication]
            summary: Check device code status
            operationId: deviceCodeStatus
            security: []
            parameters:
                - name: user_code
                  in: path
                  required: true
                  schema:
                      type: string
            responses:
                "200":
                    description: Device code details
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/auth/device/approve:
        post:
            tags: [Authentication]
            summary: Approve a CLI device login
            operationId: deviceApprove
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/DeviceApproveRequest"
            responses:
                "200":
                    description: Device approved

    /v1/auth/device/deny:
        post:
            tags: [Authentication]
            summary: Deny a CLI device login
            operationId: deviceDeny
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/DeviceApproveRequest"
            responses:
                "200":
                    description: Device denied

    # ---------------------------------------------------------------------------
    # Personal API Keys
    # ---------------------------------------------------------------------------

    /v1/auth/api-keys:
        post:
            tags: [API Keys]
            summary: Create a personal API key
            operationId: createApiKey
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateApiKeyRequest"
            responses:
                "201":
                    description: API key created (full key shown once)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ApiKeyCreatedResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
        get:
            tags: [API Keys]
            summary: List personal API keys
            operationId: listApiKeys
            responses:
                "200":
                    description: List of API keys (masked)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ApiKeyListResponse"

    /v1/auth/api-keys/{key_id}:
        delete:
            tags: [API Keys]
            summary: Revoke an API key
            operationId: revokeApiKey
            parameters:
                - name: key_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Key revoked
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/auth/export-data:
        post:
            tags: [Authentication]
            summary: Export user data (GDPR)
            description: |
                Returns a full export of the authenticated user's data including
                profile, vaults, agents, secrets metadata, and policies. Intended
                for GDPR data-portability requests. Only available to human users
                (not agents).
            operationId: exportUserData
            responses:
                "200":
                    description: User data export
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - export_version
                                    - exported_at
                                    - user
                                    - vaults
                                    - agents
                                    - secrets_metadata
                                    - policies
                                properties:
                                    export_version:
                                        type: string
                                        example: "1.0"
                                    exported_at:
                                        type: string
                                        format: date-time
                                    user:
                                        type: object
                                        required:
                                            - id
                                            - email
                                            - display_name
                                            - auth_method
                                            - created_at
                                        properties:
                                            id:
                                                type: string
                                                format: uuid
                                            email:
                                                type: string
                                                format: email
                                            display_name:
                                                type: string
                                            auth_method:
                                                type: string
                                            created_at:
                                                type: string
                                                format: date-time
                                    vaults:
                                        type: array
                                        items:
                                            type: object
                                            required: [id, name, created_at]
                                            properties:
                                                id:
                                                    type: string
                                                    format: uuid
                                                name:
                                                    type: string
                                                created_at:
                                                    type: string
                                                    format: date-time
                                    agents:
                                        type: array
                                        items:
                                            type: object
                                            required: [id, name, created_at]
                                            properties:
                                                id:
                                                    type: string
                                                    format: uuid
                                                name:
                                                    type: string
                                                created_at:
                                                    type: string
                                                    format: date-time
                                    secrets_metadata:
                                        type: array
                                        items:
                                            type: object
                                            required:
                                                - vault_id
                                                - path
                                                - type
                                                - version
                                                - created_at
                                            properties:
                                                vault_id:
                                                    type: string
                                                    format: uuid
                                                path:
                                                    type: string
                                                type:
                                                    type: string
                                                version:
                                                    type: integer
                                                created_at:
                                                    type: string
                                                    format: date-time
                                    policies:
                                        type: array
                                        items:
                                            type: object
                                            required:
                                                - id
                                                - vault_id
                                                - principal_type
                                                - principal_id
                                                - secret_path_pattern
                                                - permissions
                                                - created_at
                                            properties:
                                                id:
                                                    type: string
                                                    format: uuid
                                                vault_id:
                                                    type: string
                                                    format: uuid
                                                principal_type:
                                                    type: string
                                                principal_id:
                                                    type: string
                                                    format: uuid
                                                secret_path_pattern:
                                                    type: string
                                                permissions:
                                                    type: array
                                                    items:
                                                        type: string
                                                created_at:
                                                    type: string
                                                    format: date-time
                "403":
                    $ref: "#/components/responses/Forbidden"

    /v1/auth/devices:
        post:
            tags: [Authentication]
            summary: Register a mobile device
            description: |
                Register a new mobile device for the authenticated user. Human-only.
                The device public key is used for step-up authentication challenges.
            operationId: registerDevice
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/RegisterDeviceRequest"
            responses:
                "201":
                    description: Device registered
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/RegisterDeviceResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"
        get:
            tags: [Authentication]
            summary: List devices for current user
            description: Returns all registered mobile devices for the authenticated user.
            operationId: listDevices
            responses:
                "200":
                    description: Device list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/DeviceListResponse"

    /v1/auth/devices/{device_id}:
        delete:
            tags: [Authentication]
            summary: Revoke a device
            description: Removes a registered device, invalidating its keys and push tokens.
            operationId: revokeDevice
            parameters:
                - name: device_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Device revoked
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/auth/devices/{device_id}/challenge:
        post:
            tags: [Authentication]
            summary: Create step-up auth challenge
            description: |
                Creates a cryptographic challenge bound to a specific action (e.g. approving
                a high-risk transaction). The device signs the challenge nonce to prove
                possession of the private key.
            operationId: createDeviceChallenge
            parameters:
                - name: device_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateDeviceChallengeRequest"
            responses:
                "200":
                    description: Challenge created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/DeviceChallengeResponse"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/auth/devices/{device_id}/attest:
        post:
            tags: [Authentication]
            summary: Attest device challenge
            description: |
                Submit a signed challenge nonce to complete step-up authentication.
                Returns a short-lived step-up token that can be used for the bound action.
            operationId: attestDeviceChallenge
            parameters:
                - name: device_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/AttestDeviceChallengeRequest"
            responses:
                "200":
                    description: Attestation successful
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AttestDeviceChallengeResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/auth/devices/{device_id}/push-token:
        post:
            tags: [Authentication]
            summary: Register push notification token
            description: |
                Associates a push notification token (APNs or FCM) with a registered device
                so the server can send approval requests and alerts.
            operationId: registerPushToken
            parameters:
                - name: device_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/RegisterPushTokenRequest"
            responses:
                "204":
                    description: Push token registered
                "400":
                    $ref: "#/components/responses/BadRequest"
                "404":
                    $ref: "#/components/responses/NotFound"

    # ---------------------------------------------------------------------------
    # Vaults
    # ---------------------------------------------------------------------------

    /v1/vaults:
        post:
            tags: [Vaults]
            summary: Create a vault
            operationId: createVault
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateVaultRequest"
            responses:
                "201":
                    description: Vault created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/VaultResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
        get:
            tags: [Vaults]
            summary: List vaults
            operationId: listVaults
            responses:
                "200":
                    description: List of vaults
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/VaultListResponse"

    /v1/vaults/{vault_id}:
        get:
            tags: [Vaults]
            summary: Get vault details
            operationId: getVault
            parameters:
                - $ref: "#/components/parameters/VaultId"
            responses:
                "200":
                    description: Vault details
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/VaultResponse"
                "404":
                    $ref: "#/components/responses/NotFound"
        delete:
            tags: [Vaults]
            summary: Delete a vault
            operationId: deleteVault
            parameters:
                - $ref: "#/components/parameters/VaultId"
            responses:
                "204":
                    description: Vault deleted
                "404":
                    $ref: "#/components/responses/NotFound"

    # ---------------------------------------------------------------------------
    # CMEK (Customer-Managed Encryption Keys)
    # ---------------------------------------------------------------------------

    /v1/vaults/{vault_id}/cmek:
        post:
            tags: [CMEK]
            summary: Enable CMEK on a vault
            operationId: enableCmek
            description: |
                Enable client-side encryption on a vault. Requires Business or Enterprise plan.
                Only the key's SHA-256 fingerprint is stored — the key never touches the server.
            parameters:
                - $ref: "#/components/parameters/VaultId"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/EnableCmekRequest"
            responses:
                "200":
                    description: CMEK enabled
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/VaultResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"
        delete:
            tags: [CMEK]
            summary: Disable CMEK on a vault
            operationId: disableCmek
            description: |
                Disable client-side encryption. Existing CMEK-encrypted secrets still require
                the key to decrypt. New secrets will use HSM-only encryption.
            parameters:
                - $ref: "#/components/parameters/VaultId"
            responses:
                "200":
                    description: CMEK disabled
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/VaultResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"

    /v1/vaults/{vault_id}/cmek-rotate:
        post:
            tags: [CMEK]
            summary: Start server-assisted CMEK key rotation
            operationId: rotateCmek
            description: |
                Re-encrypts all secrets from the old CMEK key to the new one.
                Keys are passed in headers (TLS-only) and exist in server memory
                only during the rotation. Batched in groups of 100 secrets.
            parameters:
                - $ref: "#/components/parameters/VaultId"
                - name: x-cmek-old-key
                  in: header
                  required: true
                  schema:
                      type: string
                  description: Base64-encoded old CMEK key (32 bytes)
                - name: x-cmek-new-key
                  in: header
                  required: true
                  schema:
                      type: string
                  description: Base64-encoded new CMEK key (32 bytes)
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CmekRotateRequest"
            responses:
                "202":
                    description: Rotation job started
                    headers:
                        Location:
                            description: URL to poll for rotation job status
                            schema:
                                type: string
                                example: /v1/vaults/{vault_id}/cmek-rotate/{job_id}
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CmekRotationJobResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"

    /v1/vaults/{vault_id}/cmek-rotate/{job_id}:
        get:
            tags: [CMEK]
            summary: Get CMEK rotation job status
            operationId: getCmekRotationJob
            parameters:
                - $ref: "#/components/parameters/VaultId"
                - name: job_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Rotation job status
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CmekRotationJobResponse"
                "404":
                    $ref: "#/components/responses/NotFound"

    # ---------------------------------------------------------------------------
    # MPC
    # ---------------------------------------------------------------------------

    /v1/vaults/{vault_id}/mpc:
        post:
            tags: [Vaults]
            summary: Enable MPC custody on a vault
            operationId: enableMpc
            description: |
                Enable MPC custody on an existing vault. Requires Business or Enterprise plan.
                Splits secret encryption keys across multiple providers using the specified
                custody mode (e.g. 2-of-2, 2-of-3).
            parameters:
                - $ref: "#/components/parameters/VaultId"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/EnableMpcRequest"
            responses:
                "200":
                    description: MPC custody enabled
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/VaultResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    # ---------------------------------------------------------------------------
    # Secrets
    # ---------------------------------------------------------------------------

    /v1/vaults/{vault_id}/secrets:
        get:
            tags: [Secrets]
            summary: List secrets in a vault
            operationId: listSecrets
            parameters:
                - $ref: "#/components/parameters/VaultId"
                - name: prefix
                  in: query
                  schema:
                      type: string
                  description: Filter by path prefix
            responses:
                "200":
                    description: Secret metadata list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SecretListResponse"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/vaults/{vault_id}/secrets/{path}:
        put:
            tags: [Secrets]
            summary: Store or update a secret
            operationId: putSecret
            x-agentcash-auth:
                mode: paid
            x-payment-info:
                protocols: [x402]
                pricingMode: fixed
                price: "0.0075"
            parameters:
                - $ref: "#/components/parameters/VaultId"
                - $ref: "#/components/parameters/SecretPath"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/PutSecretRequest"
            responses:
                "201":
                    description: Secret created or updated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SecretCreatedResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "402":
                    $ref: "#/components/responses/PaymentRequired"
        get:
            tags: [Secrets]
            summary: Retrieve a decrypted secret
            operationId: getSecret
            x-agentcash-auth:
                mode: paid
            x-payment-info:
                protocols: [x402]
                pricingMode: fixed
                price: "0.0015"
            parameters:
                - $ref: "#/components/parameters/VaultId"
                - $ref: "#/components/parameters/SecretPath"
                - name: x-client-share
                  in: header
                  required: false
                  schema:
                      type: string
                  description: Base64-encoded client key share for MPC 2-of-2 vaults. Required when the vault uses 2-of-2 MPC custody.
            responses:
                "200":
                    description: Decrypted secret value
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SecretResponse"
                "402":
                    $ref: "#/components/responses/PaymentRequired"
                "404":
                    $ref: "#/components/responses/NotFound"
        delete:
            tags: [Secrets]
            summary: Delete a secret
            operationId: deleteSecret
            parameters:
                - $ref: "#/components/parameters/VaultId"
                - $ref: "#/components/parameters/SecretPath"
            responses:
                "204":
                    description: Secret deleted
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/vaults/{vault_id}/secret-versions/{path}:
        get:
            tags: [Secrets]
            summary: List all versions of a secret
            operationId: listSecretVersions
            parameters:
                - $ref: "#/components/parameters/VaultId"
                - $ref: "#/components/parameters/SecretPath"
            responses:
                "200":
                    description: Version list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SecretVersionListResponse"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/vaults/{vault_id}/secret-version/{path}/{version}:
        get:
            tags: [Secrets]
            summary: Retrieve a specific version of a secret
            operationId: getSecretVersion
            parameters:
                - $ref: "#/components/parameters/VaultId"
                - $ref: "#/components/parameters/SecretPath"
                - name: version
                  in: path
                  required: true
                  schema:
                      type: integer
            responses:
                "200":
                    description: Decrypted secret value at the specified version
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SecretResponse"
                "404":
                    $ref: "#/components/responses/NotFound"
                "410":
                    description: Version has been disabled or expired

    /v1/vaults/{vault_id}/secret-version-disable/{path}/{version}:
        post:
            tags: [Secrets]
            summary: Disable a specific secret version
            operationId: disableSecretVersion
            description: |
                Disables a version so it can no longer be read. The version is
                retained for audit purposes but returns 410 on read attempts.
            parameters:
                - $ref: "#/components/parameters/VaultId"
                - $ref: "#/components/parameters/SecretPath"
                - name: version
                  in: path
                  required: true
                  schema:
                      type: integer
            responses:
                "204":
                    description: Version disabled
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/vaults/{vault_id}/secret-rotate/{path}:
        post:
            tags: [Secrets]
            summary: Server-side secret rotation
            operationId: rotateSecret
            description: |
                Generates a cryptographically random value and stores it as a new
                version of the secret. The previous version is preserved in history.
                Requires rotate or write permission.
            parameters:
                - $ref: "#/components/parameters/VaultId"
                - $ref: "#/components/parameters/SecretPath"
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/RotateSecretRequest"
            responses:
                "201":
                    description: New version created with server-generated value
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SecretCreatedResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "404":
                    $ref: "#/components/responses/NotFound"

    # ---------------------------------------------------------------------------
    # Policies
    # ---------------------------------------------------------------------------

    /v1/vaults/{vault_id}/policies:
        post:
            tags: [Policies]
            summary: Create an access policy
            operationId: createPolicy
            parameters:
                - $ref: "#/components/parameters/VaultId"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreatePolicyRequest"
            responses:
                "201":
                    description: Policy created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/PolicyResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
        get:
            tags: [Policies]
            summary: List policies on a vault
            operationId: listPolicies
            parameters:
                - $ref: "#/components/parameters/VaultId"
            responses:
                "200":
                    description: Policy list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/PolicyListResponse"

    /v1/vaults/{vault_id}/policies/{policy_id}:
        put:
            tags: [Policies]
            summary: Update a policy
            operationId: updatePolicy
            parameters:
                - $ref: "#/components/parameters/VaultId"
                - $ref: "#/components/parameters/PolicyId"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UpdatePolicyRequest"
            responses:
                "200":
                    description: Policy updated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/PolicyResponse"
                "404":
                    $ref: "#/components/responses/NotFound"
        delete:
            tags: [Policies]
            summary: Revoke a policy
            operationId: deletePolicy
            parameters:
                - $ref: "#/components/parameters/VaultId"
                - $ref: "#/components/parameters/PolicyId"
            responses:
                "204":
                    description: Policy revoked
                "404":
                    $ref: "#/components/responses/NotFound"

    # ---------------------------------------------------------------------------
    # Agent Self-Enrollment (public)
    # ---------------------------------------------------------------------------

    /v1/agents/enroll:
        post:
            tags: [Agents]
            summary: Self-enroll an agent
            operationId: enrollAgent
            description: |
                Public endpoint (no auth required).

                **With `human_email`:** Creates a pending enrollment for that account's org,
                emails Allow/Deny links, and returns `approval_url` in the JSON body (use if email
                is delayed). The API key is NOT returned until the human approves.

                **Name only (omit `human_email`):** Creates a link-only pending enrollment.
                The response includes `approval_url`; the human opens it while signed in to
                approve the agent into their org.

                Anti-spam: IP rate limiting, per-email cooldown, caps on pending rows.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/EnrollAgentRequest"
            responses:
                "201":
                    description: Enrollment processed (uniform response to prevent email enumeration)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/EnrollAgentResponse"
                "429":
                    description: Rate limit exceeded

    # ---------------------------------------------------------------------------
    # Agents
    # ---------------------------------------------------------------------------

    /v1/agents:
        post:
            tags: [Agents]
            summary: Register a new agent
            operationId: createAgent
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateAgentRequest"
            responses:
                "201":
                    description: Agent created with one-time API key
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AgentCreatedResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
        get:
            tags: [Agents]
            summary: List agents
            operationId: listAgents
            responses:
                "200":
                    description: Agent list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AgentListResponse"

    /v1/agents/me:
        get:
            tags: [Agents]
            summary: Get the calling agent's own profile
            operationId: getAgentSelf
            responses:
                "200":
                    description: Agent self profile
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AgentSelfResponse"
                "403":
                    $ref: "#/components/responses/Forbidden"

    /v1/agents/{agent_id}:
        get:
            tags: [Agents]
            summary: Get agent details
            operationId: getAgent
            parameters:
                - $ref: "#/components/parameters/AgentId"
            responses:
                "200":
                    description: Agent details
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AgentResponse"
                "404":
                    $ref: "#/components/responses/NotFound"
        patch:
            tags: [Agents]
            summary: Update an agent
            operationId: updateAgent
            parameters:
                - $ref: "#/components/parameters/AgentId"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UpdateAgentRequest"
            responses:
                "200":
                    description: Agent updated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AgentResponse"
                "404":
                    $ref: "#/components/responses/NotFound"
        delete:
            tags: [Agents]
            summary: Delete an agent
            operationId: deleteAgent
            parameters:
                - $ref: "#/components/parameters/AgentId"
            responses:
                "204":
                    description: Agent deleted
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/agents/{agent_id}/rotate-key:
        post:
            tags: [Agents]
            summary: Rotate agent API key
            operationId: rotateAgentKey
            parameters:
                - $ref: "#/components/parameters/AgentId"
            responses:
                "200":
                    description: New API key returned
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AgentKeyRotatedResponse"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/agents/{agent_id}/rotate-identity-keys:
        post:
            tags: [Agents]
            summary: Rotate agent identity keys (SSH + ECDH)
            description: |
                Rotates the agent's Ed25519 SSH keypair and P-256 ECDH keypair.
                New private keys are stored in the __agent-keys vault; old keys are overwritten.
                User-only endpoint — agents cannot rotate their own identity keys.
            operationId: rotateAgentIdentityKeys
            parameters:
                - $ref: "#/components/parameters/AgentId"
            responses:
                "200":
                    description: Agent with updated public keys
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AgentResponse"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/agents/{agent_id}/smart-accounts:
        post:
            tags: [Agents]
            summary: Add a smart account (Safe) for this agent on a chain
            description: |
                Use after deploying a Safe on a new chain. Multi-chain; one Safe per chain.
                Replaces any existing entry for the same chain_id.
            operationId: addAgentSmartAccount
            parameters:
                - $ref: "#/components/parameters/AgentId"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/AddSmartAccountRequest"
            responses:
                "200":
                    description: Agent with updated smart_accounts list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AgentResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    # ---------------------------------------------------------------------------
    # Transactions (Intents API)
    # ---------------------------------------------------------------------------

    /v1/agents/{agent_id}/transactions:
        post:
            tags: [Transactions]
            summary: Submit a transaction for signing
            x-agentcash-auth:
                mode: paid
            x-payment-info:
                protocols: [x402]
                pricingMode: quote
            description: |
                Replay protection: send an optional **Idempotency-Key** header (e.g. UUID or opaque string).
                Duplicate requests with the same key within 24 hours return the cached transaction response
                (no second sign/broadcast). Omit the header for non-idempotent submissions.
            operationId: submitTransaction
            parameters:
                - $ref: "#/components/parameters/AgentId"
                - name: Idempotency-Key
                  in: header
                  required: false
                  description: Optional key for replay protection; duplicate requests return cached response.
                  schema:
                      type: string
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/SubmitTransactionRequest"
            responses:
                "201":
                    description: Transaction signed (and optionally broadcast)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TransactionResponse"
                "200":
                    description: Transaction previously created with same Idempotency-Key (replay-safe response)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TransactionResponse"
                "402":
                    $ref: "#/components/responses/PaymentRequired"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "409":
                    description: Idempotency-Key in use by another in-flight request; retry later.
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ProblemDetails"
                "422":
                    description: Simulation reverted (when simulate_first is true)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TransactionResponse"
        get:
            tags: [Transactions]
            summary: List agent transactions
            operationId: listTransactions
            parameters:
                - $ref: "#/components/parameters/AgentId"
                - $ref: "#/components/parameters/IncludeSignedTx"
            responses:
                "200":
                    description: Transaction list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TransactionListResponse"

    /v1/agents/{agent_id}/transactions/{tx_id}:
        get:
            tags: [Transactions]
            summary: Get a transaction by ID
            operationId: getTransaction
            parameters:
                - $ref: "#/components/parameters/AgentId"
                - name: tx_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                - $ref: "#/components/parameters/IncludeSignedTx"
            responses:
                "200":
                    description: Transaction details
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TransactionResponse"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/agents/{agent_id}/transactions/sign:
        post:
            tags: [Transactions]
            summary: Sign a transaction without broadcasting
            description: |
                Signs a transaction inside the server (or TEE when using Shroud) but does
                **not** broadcast it. The caller receives the raw `signed_tx` hex and
                `tx_hash` so it can submit to any RPC of its choosing.

                All agent guardrails (allowlists, value caps, daily limits) are enforced
                exactly as for the submit endpoint. The signed transaction is recorded for
                audit and daily-limit tracking with `status: "sign_only"`.
            operationId: signTransaction
            x-agentcash-auth:
                mode: paid
            x-payment-info:
                protocols: [x402]
                pricingMode: quote
            parameters:
                - $ref: "#/components/parameters/AgentId"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/SignTransactionRequest"
            responses:
                "200":
                    description: Transaction signed successfully (not broadcast)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SignTransactionResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "402":
                    $ref: "#/components/responses/PaymentRequired"

    /v1/agents/{agent_id}/transactions/simulate:
        post:
            tags: [Transactions]
            summary: Simulate a transaction via Tenderly
            operationId: simulateTransaction
            x-agentcash-auth:
                mode: paid
            x-payment-info:
                protocols: [x402]
                pricingMode: fixed
                price: "0.075"
            parameters:
                - $ref: "#/components/parameters/AgentId"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/SimulateTransactionRequest"
            responses:
                "200":
                    description: Simulation result
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SimulationResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "402":
                    $ref: "#/components/responses/PaymentRequired"

    /v1/agents/{agent_id}/transactions/simulate-bundle:
        post:
            tags: [Transactions]
            summary: Simulate a bundle of transactions
            operationId: simulateBundle
            x-agentcash-auth:
                mode: paid
            x-payment-info:
                protocols: [x402]
                pricingMode: fixed
                price: "0.075"
            parameters:
                - $ref: "#/components/parameters/AgentId"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/SimulateBundleRequest"
            responses:
                "200":
                    description: Bundle simulation results
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/BundleSimulationResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "402":
                    $ref: "#/components/responses/PaymentRequired"

    # ---------------------------------------------------------------------------
    # Agent Signing Keys (Multi-Chain)
    # ---------------------------------------------------------------------------

    /v1/agents/{agent_id}/signing-keys:
        post:
            tags: [Signing Keys]
            summary: Provision a signing key for a chain
            operationId: createSigningKey
            parameters:
                - $ref: "#/components/parameters/AgentId"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateSigningKeyRequest"
            responses:
                "201":
                    description: Signing key created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SigningKeyResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "409":
                    $ref: "#/components/responses/Conflict"
        get:
            tags: [Signing Keys]
            summary: List signing keys for an agent
            operationId: listSigningKeys
            parameters:
                - $ref: "#/components/parameters/AgentId"
            responses:
                "200":
                    description: Signing keys list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SigningKeyListResponse"

    /v1/agents/{agent_id}/signing-keys/{chain}/rotate:
        post:
            tags: [Signing Keys]
            summary: Rotate a signing key for a chain
            operationId: rotateSigningKey
            parameters:
                - $ref: "#/components/parameters/AgentId"
                - name: chain
                  in: path
                  required: true
                  schema:
                      type: string
            responses:
                "200":
                    description: Rotated signing key
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SigningKeyResponse"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/agents/{agent_id}/signing-keys/{chain}:
        delete:
            tags: [Signing Keys]
            summary: Deactivate a signing key for a chain
            operationId: deactivateSigningKey
            parameters:
                - $ref: "#/components/parameters/AgentId"
                - name: chain
                  in: path
                  required: true
                  schema:
                      type: string
            responses:
                "204":
                    description: Key deactivated
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/agents/{agent_id}/signing-keys/{chain}/export:
        post:
            tags: [Signing Keys]
            summary: Export a signing key (private key included)
            description: |
                Export the private key for an agent's signing key. Requires re-authentication
                via the X-Auth-Confirm header containing the user's account password.
                Human users only — agents cannot export keys.
            operationId: exportSigningKey
            parameters:
                - $ref: "#/components/parameters/AgentId"
                - name: chain
                  in: path
                  required: true
                  schema:
                      type: string
                - name: X-Auth-Confirm
                  in: header
                  required: true
                  description: Account password for re-authentication
                  schema:
                      type: string
                      format: password
            responses:
                "200":
                    description: Signing key exported successfully
                    content:
                        application/json:
                            schema:
                                type: object
                                required: [chain, curve, public_key, private_key, key_version, agent_id]
                                properties:
                                    chain:
                                        type: string
                                    curve:
                                        type: string
                                    public_key:
                                        type: string
                                    address:
                                        type: string
                                    private_key:
                                        type: string
                                    key_version:
                                        type: integer
                                    agent_id:
                                        type: string
                                        format: uuid
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/agents/{agent_id}/signing-keys/{chain}/balance:
        get:
            tags: [Signing Keys]
            summary: Get signing key balance
            description: |
                Returns the native token balance for the agent's signing key address
                on the specified chain.
            operationId: getSigningKeyBalance
            security:
                - BearerAuth: []
            parameters:
                - $ref: "#/components/parameters/AgentId"
                - name: chain
                  in: path
                  required: true
                  schema:
                      type: string
            responses:
                "200":
                    description: Signing key balance
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SigningKeyBalanceResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    # ---------------------------------------------------------------------------
    # Bankr Dynamic Key Vending
    # ---------------------------------------------------------------------------

    /v1/agents/{agent_id}/bankr-keys/lease:
        post:
            tags: [Bankr Keys]
            summary: Lease a short-lived Bankr wallet API key
            description: |
                Provision a scoped, time-limited Bankr wallet API key for an agent.
                **Privileged, deny-by-default:** agent callers need an explicit access policy
                on `agents/{agent_id}/bankr/*` in the `__agent-keys` vault (JWT scope
                `agents/{agent_id}/bankr/lease`). Agents may only lease for their own ID.
                The `bk_usr_` key is **omitted** from the JSON response for agent JWTs —
                stored server-side for Shroud resolution. Human callers receive `api_key` once.
                Requires `BANKR_PARTNER_KEY` on Vault. Agent default TTL 15 min when omitted;
                human/org default 1 hour (`BANKR_DEFAULT_LEASE_TTL_SECS`). Recommend 5–15 min
                for autonomous agents. Max TTL 24 hours. Max 5 concurrent leases per agent.
            operationId: leaseBankrKey
            parameters:
                - $ref: "#/components/parameters/AgentId"
            requestBody:
                required: false
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/LeaseBankrKeyRequest"
            responses:
                "201":
                    description: Bankr key leased
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/LeaseBankrKeyResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"

    /v1/agents/{agent_id}/bankr-keys:
        get:
            tags: [Bankr Keys]
            summary: List active Bankr key leases for an agent
            operationId: listBankrKeys
            parameters:
                - $ref: "#/components/parameters/AgentId"
            responses:
                "200":
                    description: Active leases (no secret values)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/BankrKeyLeaseListResponse"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/agents/{agent_id}/bankr-keys/{lease_id}:
        delete:
            tags: [Bankr Keys]
            summary: Revoke an active Bankr key lease
            operationId: revokeBankrKey
            parameters:
                - $ref: "#/components/parameters/AgentId"
                - name: lease_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Lease revoked
                "404":
                    $ref: "#/components/responses/NotFound"

    # ---------------------------------------------------------------------------
    # Unified Signing Intent
    # ---------------------------------------------------------------------------

    /v1/agents/{agent_id}/sign:
        post:
            tags: [Signing]
            summary: Unified signing intent (EIP-191, EIP-712, EIP-2718 types 0-4)
            operationId: signIntent
            parameters:
                - $ref: "#/components/parameters/AgentId"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/SignIntentRequest"
            responses:
                "200":
                    description: Signed result
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SignIntentResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"

    # ---------------------------------------------------------------------------
    # Execution Intents
    # ---------------------------------------------------------------------------

    /v1/agents/{agent_id}/bindings:
        post:
            tags: [Execution Intents]
            summary: Create a binding
            operationId: createBinding
            parameters:
                - $ref: "#/components/parameters/AgentId"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateBindingRequest"
            responses:
                "201":
                    description: Binding created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/BindingResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"
        get:
            tags: [Execution Intents]
            summary: List bindings
            operationId: listBindings
            parameters:
                - $ref: "#/components/parameters/AgentId"
            responses:
                "200":
                    description: Binding list
                    content:
                        application/json:
                            schema:
                                type: object
                                required: [bindings]
                                properties:
                                    bindings:
                                        type: array
                                        items:
                                            $ref: "#/components/schemas/BindingResponse"
                "403":
                    $ref: "#/components/responses/Forbidden"

    /v1/agents/{agent_id}/bindings/{binding_id}:
        get:
            tags: [Execution Intents]
            summary: Get binding
            operationId: getBinding
            parameters:
                - $ref: "#/components/parameters/AgentId"
                - name: binding_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Binding details
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/BindingResponse"
                "404":
                    $ref: "#/components/responses/NotFound"
        patch:
            tags: [Execution Intents]
            summary: Update binding
            operationId: updateBinding
            parameters:
                - $ref: "#/components/parameters/AgentId"
                - name: binding_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UpdateBindingRequest"
            responses:
                "200":
                    description: Binding updated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/BindingResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "404":
                    $ref: "#/components/responses/NotFound"
        delete:
            tags: [Execution Intents]
            summary: Delete binding
            operationId: deleteBinding
            parameters:
                - $ref: "#/components/parameters/AgentId"
                - name: binding_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Binding deleted
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/agents/{agent_id}/bindings/{binding_id}/test:
        post:
            tags: [Execution Intents]
            summary: Test binding connectivity
            operationId: testBinding
            parameters:
                - $ref: "#/components/parameters/AgentId"
                - name: binding_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: false
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                timeout_ms:
                                    type: integer
                                    description: Connection test timeout in milliseconds
            responses:
                "200":
                    description: Test result
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TestBindingResponse"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/agents/{agent_id}/bindings/{binding_id}/rotate-credential:
        post:
            tags: [Execution Intents]
            summary: Rotate a binding credential
            description: Overwrite the stored credential for a binding without touching its config or guardrails. Human-only. The credential value is never returned.
            operationId: rotateBindingCredential
            parameters:
                - $ref: "#/components/parameters/AgentId"
                - name: binding_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [credential]
                            properties:
                                credential:
                                    description: New credential material (object or string). Stored server-side.
            responses:
                "200":
                    description: Updated binding
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/BindingResponse"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/agents/{agent_id}/execute:
        post:
            tags: [Execution Intents]
            summary: Execute an intent
            operationId: executeIntent
            parameters:
                - $ref: "#/components/parameters/AgentId"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/ExecuteRequest"
            responses:
                "200":
                    description: Execution result
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ExecuteResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"

    /v1/agents/{agent_id}/executions:
        get:
            tags: [Execution Intents]
            summary: List execution events
            operationId: listExecutions
            parameters:
                - $ref: "#/components/parameters/AgentId"
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      default: 50
                - name: offset
                  in: query
                  required: false
                  schema:
                      type: integer
                      default: 0
            responses:
                "200":
                    description: Execution event list
                    content:
                        application/json:
                            schema:
                                type: object
                                required: [events]
                                properties:
                                    events:
                                        type: array
                                        items:
                                            $ref: "#/components/schemas/ExecutionEventResponse"
                "403":
                    $ref: "#/components/responses/Forbidden"

    # ---------------------------------------------------------------------------
    # Chains
    # ---------------------------------------------------------------------------

    /v1/chains:
        get:
            tags: [Chains]
            summary: List enabled chains
            operationId: listChains
            security: []
            responses:
                "200":
                    description: Chain list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ChainListResponse"

    /v1/chains/{identifier}:
        get:
            tags: [Chains]
            summary: Get chain by name or ID
            operationId: getChain
            security: []
            parameters:
                - name: identifier
                  in: path
                  required: true
                  schema:
                      type: string
                  description: Chain name (e.g. "ethereum") or numeric chain ID
            responses:
                "200":
                    description: Chain details
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ChainResponse"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/admin/chains:
        get:
            tags: [Chains]
            summary: List all chains including disabled (admin)
            operationId: adminListChains
            responses:
                "200":
                    description: Full chain list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ChainListResponse"
        post:
            tags: [Chains]
            summary: Add a chain (admin)
            operationId: createChain
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateChainRequest"
            responses:
                "201":
                    description: Chain added
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ChainResponse"

    /v1/admin/chains/{chain_id}:
        put:
            tags: [Chains]
            summary: Update a chain (admin)
            operationId: updateChain
            parameters:
                - name: chain_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UpdateChainRequest"
            responses:
                "200":
                    description: Chain updated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ChainResponse"
        delete:
            tags: [Chains]
            summary: Remove a chain (admin)
            operationId: deleteChain
            parameters:
                - name: chain_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Chain removed

    # ---------------------------------------------------------------------------
    # Sharing
    # ---------------------------------------------------------------------------

    /v1/secrets/{secret_id}/share:
        post:
            tags: [Sharing]
            summary: Create a share link for a secret
            operationId: createShare
            x-agentcash-auth:
                mode: paid
            x-payment-info:
                protocols: [x402]
                pricingMode: fixed
                price: "0.003"
            parameters:
                - name: secret_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateShareRequest"
            responses:
                "201":
                    description: Share created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ShareResponse"
                "402":
                    $ref: "#/components/responses/PaymentRequired"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/share/{share_id}:
        get:
            tags: [Sharing]
            summary: Access a shared secret
            operationId: accessShare
            security: []
            x-agentcash-auth:
                mode: paid
            x-payment-info:
                protocols: [x402]
                pricingMode: fixed
                price: "0.0015"
            parameters:
                - name: share_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Shared secret value
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SharedSecretResponse"
                "402":
                    $ref: "#/components/responses/PaymentRequired"
                "404":
                    $ref: "#/components/responses/NotFound"
        delete:
            tags: [Sharing]
            summary: Revoke a share link
            operationId: revokeShare
            parameters:
                - name: share_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Share revoked

    /v1/shares/outbound:
        get:
            tags: [Sharing]
            summary: List shares you have sent
            operationId: listOutboundShares
            responses:
                "200":
                    description: Outbound share list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ShareListResponse"

    /v1/shares/inbound:
        get:
            tags: [Sharing]
            summary: List shares sent to you
            operationId: listInboundShares
            responses:
                "200":
                    description: Inbound share list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ShareListResponse"

    /v1/shares/{share_id}/accept:
        post:
            tags: [Sharing]
            summary: Accept an inbound share
            operationId: acceptShare
            parameters:
                - name: share_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Share accepted

    /v1/shares/{share_id}/decline:
        post:
            tags: [Sharing]
            summary: Decline an inbound share
            operationId: declineShare
            parameters:
                - name: share_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Share declined

    # ---------------------------------------------------------------------------
    # Organization
    # ---------------------------------------------------------------------------

    /v1/org/members:
        get:
            tags: [Organization]
            summary: List organization members
            operationId: listOrgMembers
            responses:
                "200":
                    description: Member list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/OrgMemberListResponse"

    /v1/org/agent-keys-vault:
        get:
            tags: [Organization]
            summary: Get the org's __agent-keys vault id
            description: Returns the vault id for the caller's org agent-keys vault (used for revealing agent identity keys). Users only; 404 if the vault does not exist.
            operationId: getAgentKeysVault
            responses:
                "200":
                    description: Agent-keys vault id
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AgentKeysVaultResponse"
                "404":
                    description: Agent-keys vault not found

    /v1/org/bankr-config:
        get:
            tags: [Organization]
            summary: Get org Bankr partner configuration
            description: Returns whether the org has configured Bankr BYOK (partner key prefix and default wallet only — never the secret). Users only.
            operationId: getOrgBankrConfig
            responses:
                "200":
                    description: Bankr configuration status
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/OrgBankrConfigResponse"
        put:
            tags: [Organization]
            summary: Set org Bankr partner configuration
            description: Store or replace the org's Bankr partner key (`bk_ptr_...`) and optional default wallet (`wlt_...`). Owner/admin only. Partner key encrypted at rest.
            operationId: upsertOrgBankrConfig
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UpsertOrgBankrConfigRequest"
            responses:
                "200":
                    description: Configuration saved
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/OrgBankrConfigResponse"
        delete:
            tags: [Organization]
            summary: Remove org Bankr partner configuration
            description: Delete BYOK credentials for the org. Owner/admin only.
            operationId: deleteOrgBankrConfig
            responses:
                "204":
                    description: Configuration removed
                "404":
                    description: Configuration not found

    /v1/org/invite:
        post:
            tags: [Organization]
            summary: Invite a member by email
            operationId: inviteMember
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/InviteMemberRequest"
            responses:
                "200":
                    description: Invitation sent
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/InviteMemberResponse"

    /v1/org/members/{user_id}:
        patch:
            tags: [Organization]
            summary: Update a member's role
            operationId: updateMemberRole
            parameters:
                - name: user_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UpdateMemberRoleRequest"
            responses:
                "200":
                    description: Role updated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/OrgMemberResponse"
        delete:
            tags: [Organization]
            summary: Remove a member from the organization
            operationId: removeMember
            parameters:
                - name: user_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Member removed

    # ---------------------------------------------------------------------------
    # Billing
    # ---------------------------------------------------------------------------

    /v1/billing/usage:
        get:
            tags: [Billing]
            summary: Get usage summary (legacy)
            operationId: billingUsage
            responses:
                "200":
                    description: Usage summary
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/UsageSummaryResponse"

    /v1/billing/history:
        get:
            tags: [Billing]
            summary: Get usage event history (legacy)
            operationId: billingHistory
            parameters:
                - name: limit
                  in: query
                  schema:
                      type: integer
                      default: 50
            responses:
                "200":
                    description: Usage event list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/UsageHistoryResponse"

    /v1/billing/subscribe:
        post:
            tags: [Billing]
            summary: Start a subscription via Stripe Checkout
            operationId: billingSubscribe
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/SubscribeRequest"
            responses:
                "200":
                    description: Checkout URL
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CheckoutUrlResponse"

    /v1/billing/portal:
        post:
            tags: [Billing]
            summary: Open Stripe Customer Portal
            operationId: billingPortal
            responses:
                "200":
                    description: Portal URL
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/PortalUrlResponse"

    /v1/billing/subscription:
        get:
            tags: [Billing]
            summary: Get subscription, usage, and credit summary
            operationId: billingSubscription
            responses:
                "200":
                    description: Full billing summary
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SubscriptionResponse"

    /v1/billing/credits/topup:
        post:
            tags: [Billing]
            summary: Top up prepaid credits via Stripe
            operationId: billingCreditTopup
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/TopupRequest"
            responses:
                "200":
                    description: Checkout URL for top-up
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CheckoutUrlResponse"

    /v1/billing/credits/balance:
        get:
            tags: [Billing]
            summary: Get credit balance
            operationId: billingCreditBalance
            responses:
                "200":
                    description: Credit balance
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CreditBalanceResponse"

    /v1/billing/credits/transactions:
        get:
            tags: [Billing]
            summary: Get credit transaction ledger
            operationId: billingCreditTransactions
            parameters:
                - name: page
                  in: query
                  schema:
                      type: integer
                      default: 1
                - name: limit
                  in: query
                  schema:
                      type: integer
                      default: 50
            responses:
                "200":
                    description: Credit ledger
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CreditTransactionsListResponse"

    # ---------------------------------------------------------------------------
    # LLM Token Billing
    # ---------------------------------------------------------------------------

    /v1/billing/llm-token-billing:
        get:
            tags: [Billing]
            summary: Get LLM token billing status
            operationId: getLlmTokenBilling
            description: >
                Returns whether LLM token billing is enabled, optional Stripe billing credit balance
                (metered scope), and estimated cycle usage from the upcoming invoice—including per-line
                metered rows when Stripe returns them (amounts; quantities such as tokens when present).
            responses:
                "200":
                    description: LLM token billing status
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/LlmTokenBillingStatus"

    /v1/billing/llm-token-billing/subscribe:
        post:
            tags: [Billing]
            summary: Subscribe to LLM token billing
            operationId: subscribeLlmTokenBilling
            description: >
                Creates a Stripe Checkout session for the LLM token billing pricing plan.
                Returns a checkout URL to redirect the user. After the user completes checkout,
                a webhook activates LLM billing for the org.
            responses:
                "200":
                    description: Stripe Checkout URL
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/LlmCheckoutResponse"

    /v1/billing/llm-token-billing/disable:
        post:
            tags: [Billing]
            summary: Disable LLM token billing
            operationId: disableLlmTokenBilling
            description: >
                Disables LLM token billing for the org and cancels all active
                Stripe subscriptions for the LLM pricing plan. Agents will fall
                back to direct provider routing. You can re-enable it at any time.
            responses:
                "200":
                    description: LLM billing disabled
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/LlmDisableResponse"

    /v1/billing/overage-method:
        patch:
            tags: [Billing]
            summary: Set overage payment method
            operationId: billingOverageMethod
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/OverageMethodRequest"
            responses:
                "200":
                    description: Overage method updated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/OverageMethodResponse"

    /v1/billing/webhooks:
        post:
            tags: [Billing]
            summary: Stripe webhook receiver
            operationId: billingWebhook
            security: []
            responses:
                "200":
                    description: Webhook processed

    # ---------------------------------------------------------------------------
    # Audit
    # ---------------------------------------------------------------------------

    /v1/audit/events:
        get:
            tags: [Audit]
            summary: Query audit events
            operationId: queryAuditEvents
            x-agentcash-auth:
                mode: paid
            x-payment-info:
                protocols: [x402]
                pricingMode: fixed
                price: "0.0008"
            parameters:
                - name: resource_id
                  in: query
                  schema:
                      type: string
                - name: actor_id
                  in: query
                  schema:
                      type: string
                - name: action
                  in: query
                  schema:
                      type: string
                - name: from
                  in: query
                  schema:
                      type: string
                      format: date-time
                - name: to
                  in: query
                  schema:
                      type: string
                      format: date-time
                - name: limit
                  in: query
                  schema:
                      type: integer
                      default: 100
                - name: offset
                  in: query
                  schema:
                      type: integer
                      default: 0
            responses:
                "200":
                    description: Audit events
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AuditEventsResponse"
                "402":
                    $ref: "#/components/responses/PaymentRequired"

    # ---------------------------------------------------------------------------
    # Security (IP Rules)
    # ---------------------------------------------------------------------------

    /v1/security/ip-rules:
        get:
            tags: [Security]
            summary: List IP rules
            operationId: listIpRules
            responses:
                "200":
                    description: IP rule list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/IpRulesListResponse"
        post:
            tags: [Security]
            summary: Create an IP rule
            operationId: createIpRule
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateIpRuleRequest"
            responses:
                "201":
                    description: Rule created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/IpRuleResponse"

    /v1/security/ip-rules/{rule_id}:
        delete:
            tags: [Security]
            summary: Delete an IP rule
            operationId: deleteIpRule
            parameters:
                - name: rule_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Rule deleted

    # ---------------------------------------------------------------------------
    # Treasury
    # ---------------------------------------------------------------------------

    /v1/treasury:
        post:
            tags: [Treasury]
            summary: Create a treasury (Safe multisig)
            operationId: createTreasury
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateTreasuryRequest"
            responses:
                "201":
                    description: Treasury created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "401":
                    $ref: "#/components/responses/Unauthorized"
        get:
            tags: [Treasury]
            summary: List treasuries
            operationId: listTreasuries
            security:
                - BearerAuth: []
            responses:
                "200":
                    description: List of treasuries
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    treasuries:
                                        type: array
                                        items:
                                            $ref: "#/components/schemas/TreasuryResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"

    /v1/treasury/{treasury_id}:
        get:
            tags: [Treasury]
            summary: Get treasury details
            operationId: getTreasury
            security:
                - BearerAuth: []
            parameters:
                - name: treasury_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Treasury details
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryResponse"
                "404":
                    $ref: "#/components/responses/NotFound"
        patch:
            tags: [Treasury]
            summary: Update treasury name and/or threshold
            operationId: updateTreasury
            security:
                - BearerAuth: []
            parameters:
                - name: treasury_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UpdateTreasuryRequest"
            responses:
                "200":
                    description: Treasury updated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "404":
                    $ref: "#/components/responses/NotFound"
        delete:
            tags: [Treasury]
            summary: Delete a treasury and its signers
            operationId: deleteTreasury
            security:
                - BearerAuth: []
            parameters:
                - name: treasury_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Treasury deleted
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/treasury/{treasury_id}/signers:
        post:
            tags: [Treasury]
            summary: Add a signer to a treasury
            operationId: addTreasurySigner
            security:
                - BearerAuth: []
            parameters:
                - name: treasury_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/AddSignerRequest"
            responses:
                "201":
                    description: Signer added
                "400":
                    $ref: "#/components/responses/BadRequest"

    /v1/treasury/{treasury_id}/signers/{signer_id}:
        delete:
            tags: [Treasury]
            summary: Remove a signer from a treasury
            operationId: removeTreasurySigner
            security:
                - BearerAuth: []
            parameters:
                - name: treasury_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                - name: signer_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Signer removed
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/treasury/{treasury_id}/access-requests:
        post:
            tags: [Treasury]
            summary: Request access to a treasury (agent-only)
            operationId: requestTreasuryAccess
            security:
                - BearerAuth: []
            parameters:
                - name: treasury_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "201":
                    description: Access request created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AccessRequestResponse"
                "403":
                    $ref: "#/components/responses/Forbidden"
        get:
            tags: [Treasury]
            summary: List access requests for a treasury
            operationId: listTreasuryAccessRequests
            security:
                - BearerAuth: []
            parameters:
                - name: treasury_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: List of access requests
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    requests:
                                        type: array
                                        items:
                                            $ref: "#/components/schemas/AccessRequestResponse"

    /v1/treasury/{treasury_id}/access-requests/{request_id}/approve:
        post:
            tags: [Treasury]
            summary: Approve an access request
            operationId: approveTreasuryAccess
            security:
                - BearerAuth: []
            parameters:
                - name: treasury_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                - name: request_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Access request approved
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/treasury/{treasury_id}/access-requests/{request_id}/deny:
        post:
            tags: [Treasury]
            summary: Deny an access request
            operationId: denyTreasuryAccess
            security:
                - BearerAuth: []
            parameters:
                - name: treasury_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                - name: request_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Access request denied
                "404":
                    $ref: "#/components/responses/NotFound"

    # ---------------------------------------------------------------------------
    # Treasury Proposals (multisig propose / sign / execute)
    # ---------------------------------------------------------------------------

    /v1/treasury/{treasury_id}/proposals:
        post:
            tags: [Treasury Proposals]
            summary: Create a multisig proposal
            description: |
                Create a new Safe multisig transaction proposal. The proposer must be a
                treasury signer or an agent with an active delegation for the treasury.
                If auto-approve rules match, the agent's signature is auto-inserted and
                auto-execute fires if threshold is met.
            operationId: createTreasuryProposal
            security:
                - BearerAuth: []
            parameters:
                - name: treasury_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateTreasuryProposalRequest"
            responses:
                "201":
                    description: Proposal created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryProposalResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"
        get:
            tags: [Treasury Proposals]
            summary: List proposals for a treasury
            operationId: listTreasuryProposals
            security:
                - BearerAuth: []
            parameters:
                - name: treasury_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                - name: status
                  in: query
                  required: false
                  schema:
                      type: string
                      enum: [pending, approved, executing, executed, rejected, expired]
            responses:
                "200":
                    description: Proposal list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryProposalListResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"

    /v1/treasury/{treasury_id}/proposals/{proposal_id}:
        get:
            tags: [Treasury Proposals]
            summary: Get a proposal with collected signatures
            operationId: getTreasuryProposal
            security:
                - BearerAuth: []
            parameters:
                - name: treasury_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                - name: proposal_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Proposal details
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryProposalResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "404":
                    $ref: "#/components/responses/NotFound"
        delete:
            tags: [Treasury Proposals]
            summary: Cancel a pending proposal (proposer only)
            operationId: cancelTreasuryProposal
            security:
                - BearerAuth: []
            parameters:
                - name: treasury_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                - name: proposal_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Proposal cancelled
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/treasury/{treasury_id}/proposals/{proposal_id}/sign:
        post:
            tags: [Treasury Proposals]
            summary: Sign a proposal (approve or reject)
            description: |
                Submit an EIP-712 signature for a pending proposal. When approve signatures
                reach the Safe threshold, auto-execute fires: signatures are collected in
                address-sorted order, `execTransaction` calldata is built, and the transaction
                is broadcast via RPC.
            operationId: signTreasuryProposal
            security:
                - BearerAuth: []
            parameters:
                - name: treasury_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                - name: proposal_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/SignTreasuryProposalRequest"
            responses:
                "200":
                    description: Signature recorded (may include executed_tx_hash if auto-executed)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryProposalResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/treasury/{treasury_id}/proposals/{proposal_id}/execute:
        post:
            tags: [Treasury Proposals]
            summary: Force-execute a proposal if threshold is met (user-only)
            operationId: executeTreasuryProposal
            security:
                - BearerAuth: []
            parameters:
                - name: treasury_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                - name: proposal_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Proposal executed
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryProposalResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    # ---------------------------------------------------------------------------
    # Treasury Wallets (multi-chain key generation for human users)
    # ---------------------------------------------------------------------------

    /v1/treasury/wallets/generate:
        post:
            tags: [Treasury Wallets]
            summary: Generate multi-chain wallets for the authenticated user
            description: |
                Generates keypairs for the requested chains (or all supported chains if omitted).
                Private keys are stored in a per-org `__treasury-keys` vault with tier-appropriate
                MPC custody. Skips chains where the user already has an active wallet. Requires
                Pro or higher billing tier. Human users only — agents get 403.
            operationId: generateTreasuryWallets
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/GenerateTreasuryWalletsRequest"
            responses:
                "201":
                    description: Wallets generated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryWalletListResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"

    /v1/treasury/wallets:
        get:
            tags: [Treasury Wallets]
            summary: List the authenticated user's treasury wallets
            operationId: listTreasuryWallets
            security:
                - BearerAuth: []
            responses:
                "200":
                    description: Wallet list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryWalletListResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"

    /v1/treasury/wallets/{chain}:
        get:
            tags: [Treasury Wallets]
            summary: Get the user's active wallet for a specific chain
            operationId: getTreasuryWallet
            security:
                - BearerAuth: []
            parameters:
                - name: chain
                  in: path
                  required: true
                  schema:
                      type: string
                  description: "Chain name (e.g. ethereum, solana, bitcoin)"
            responses:
                "200":
                    description: Wallet details
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryWalletResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"
        delete:
            tags: [Treasury Wallets]
            summary: Deactivate the user's wallet for a specific chain
            operationId: deactivateTreasuryWallet
            security:
                - BearerAuth: []
            parameters:
                - name: chain
                  in: path
                  required: true
                  schema:
                      type: string
            responses:
                "204":
                    description: Wallet deactivated
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"

    /v1/treasury/wallets/{chain}/export:
        post:
            tags: [Treasury Wallets]
            summary: Export the private key for a treasury wallet
            description: |
                Returns the raw private key hex for the user's active wallet on
                the given chain. Requires re-authentication via the `X-Auth-Confirm`
                header (account password). Audit-logged as `treasury_wallet.export`.
                Human users only.
            operationId: exportTreasuryWallet
            security:
                - BearerAuth: []
            parameters:
                - name: chain
                  in: path
                  required: true
                  schema:
                      type: string
                - name: X-Auth-Confirm
                  in: header
                  required: true
                  description: Account password for re-authentication
                  schema:
                      type: string
                      format: password
            responses:
                "200":
                    description: Private key exported
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryWalletExportResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/treasury/wallets/{chain}/rotate:
        post:
            tags: [Treasury Wallets]
            summary: Rotate the user's wallet key for a chain
            description: |
                Generates a new keypair, deactivates the old wallet, and creates a
                new active wallet. The old private key version is retained in the
                vault for audit. Requires Pro or higher.
            operationId: rotateTreasuryWallet
            security:
                - BearerAuth: []
            parameters:
                - name: chain
                  in: path
                  required: true
                  schema:
                      type: string
            responses:
                "200":
                    description: Wallet rotated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryWalletResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/treasury/wallets/{chain}/balance:
        get:
            tags: [Treasury Wallets]
            summary: Get wallet balance
            description: |
                Returns the native and token balances for the user's active wallet
                on the specified chain.
            operationId: getTreasuryWalletBalance
            security:
                - BearerAuth: []
            parameters:
                - name: chain
                  in: path
                  required: true
                  schema:
                      type: string
                - name: tokens
                  in: query
                  required: false
                  description: Optional list of ERC-20 contract addresses to query balances for
                  schema:
                      type: array
                      items:
                          type: string
            responses:
                "200":
                    description: Wallet balance
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryWalletBalanceResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/treasury/wallets/{chain}/send:
        post:
            tags: [Treasury Wallets]
            summary: Send from treasury wallet
            description: |
                Signs and broadcasts a transaction from the user's active wallet on
                the specified chain. Requires re-authentication via `X-Auth-Confirm`
                header (account password). Human users only.
            operationId: sendFromTreasuryWallet
            security:
                - BearerAuth: []
            parameters:
                - name: chain
                  in: path
                  required: true
                  schema:
                      type: string
                - name: X-Auth-Confirm
                  in: header
                  required: true
                  description: Account password for re-authentication
                  schema:
                      type: string
                      format: password
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/TreasuryWalletSendRequest"
            responses:
                "200":
                    description: Transaction sent
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryWalletSendResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/treasury/wallets/{chain}/swap:
        post:
            tags: [Treasury Wallets]
            summary: Swap tokens via DEX aggregator
            description: |
                Executes a token swap through a DEX aggregator from the user's active
                wallet on the specified chain. Requires re-authentication via
                `X-Auth-Confirm` header (account password). Human users only.
            operationId: swapFromTreasuryWallet
            security:
                - BearerAuth: []
            parameters:
                - name: chain
                  in: path
                  required: true
                  schema:
                      type: string
                - name: X-Auth-Confirm
                  in: header
                  required: true
                  description: Account password for re-authentication
                  schema:
                      type: string
                      format: password
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/TreasuryWalletSwapRequest"
            responses:
                "200":
                    description: Swap executed
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/TreasuryWalletSwapResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/treasury/wallets/spend-policy:
        get:
            tags: [Treasury Wallets]
            summary: Get effective spend policy for current user
            description: |
                Returns the effective spend policy governing the authenticated user's
                wallet transactions. Resolves from per-user override (if set) or the
                app-wide default. Returns null if no policy is configured.
            operationId: getEffectiveSpendPolicy
            security:
                - BearerAuth: []
            responses:
                "200":
                    description: Effective spend policy
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    policy:
                                        nullable: true
                                        allOf:
                                            - $ref: "#/components/schemas/SpendPolicyResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"

    # ---------------------------------------------------------------------------
    # Webhooks
    # ---------------------------------------------------------------------------

    /v1/webhooks:
        post:
            tags: [Webhooks]
            summary: Register a webhook
            operationId: createWebhook
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateWebhookRequest"
            responses:
                "201":
                    description: Webhook registered
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/WebhookCreatedResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "401":
                    $ref: "#/components/responses/Unauthorized"
        get:
            tags: [Webhooks]
            summary: List webhooks
            operationId: listWebhooks
            security:
                - BearerAuth: []
            responses:
                "200":
                    description: Webhook list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/WebhookListResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"

    /v1/webhooks/{id}:
        get:
            tags: [Webhooks]
            summary: Get webhook
            operationId: getWebhook
            security:
                - BearerAuth: []
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Webhook details
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/WebhookResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "404":
                    $ref: "#/components/responses/NotFound"
        patch:
            tags: [Webhooks]
            summary: Update webhook
            operationId: updateWebhook
            security:
                - BearerAuth: []
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UpdateWebhookRequest"
            responses:
                "200":
                    description: Webhook updated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/WebhookResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "404":
                    $ref: "#/components/responses/NotFound"
        delete:
            tags: [Webhooks]
            summary: Delete webhook
            operationId: deleteWebhook
            security:
                - BearerAuth: []
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Webhook deleted
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "404":
                    $ref: "#/components/responses/NotFound"

    # ---------------------------------------------------------------------------
    # Admin
    # ---------------------------------------------------------------------------

    /v1/admin/settings:
        get:
            tags: [Admin]
            summary: List platform settings
            operationId: adminListSettings
            responses:
                "200":
                    description: Settings list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SettingsListResponse"

    /v1/admin/settings/{key}:
        put:
            tags: [Admin]
            summary: Update a platform setting
            operationId: adminUpdateSetting
            parameters:
                - name: key
                  in: path
                  required: true
                  schema:
                      type: string
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UpdateSettingRequest"
            responses:
                "200":
                    description: Setting updated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SettingResponse"
        delete:
            tags: [Admin]
            summary: Delete a platform setting
            operationId: adminDeleteSetting
            parameters:
                - name: key
                  in: path
                  required: true
                  schema:
                      type: string
            responses:
                "204":
                    description: Setting deleted

    /v1/admin/x402:
        get:
            tags: [Admin]
            summary: Get x402 payment config
            operationId: adminGetX402Config
            responses:
                "200":
                    description: x402 config
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/X402ConfigResponse"
        put:
            tags: [Admin]
            summary: Update x402 payment config
            operationId: adminUpdateX402Config
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/X402ConfigResponse"
            responses:
                "200":
                    description: Config updated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/X402ConfigResponse"

    /v1/admin/users:
        get:
            tags: [Admin]
            summary: List all platform users
            operationId: adminListUsers
            responses:
                "200":
                    description: User list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AdminUsersListResponse"

    /v1/admin/users/{user_id}:
        delete:
            tags: [Admin]
            summary: Delete a user (cascade)
            operationId: adminDeleteUser
            parameters:
                - name: user_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: User deleted

    /v1/admin/orgs/{org_id}/limits:
        get:
            tags: [Admin]
            summary: Get org limits
            operationId: adminGetOrgLimits
            parameters:
                - name: org_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Org limits
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/OrgLimitsResponse"
        put:
            tags: [Admin]
            summary: Update org limits
            operationId: adminUpdateOrgLimits
            parameters:
                - name: org_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UpdateOrgLimitsRequest"
            responses:
                "200":
                    description: Limits updated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/OrgLimitsResponse"

    /v1/admin/orgs/{org_id}/billing-tier:
        put:
            tags: [Admin]
            summary: Set org billing tier (without Stripe)
            operationId: adminSetBillingTier
            description: |
                Manually set an organization's billing tier to free, pro, business, or enterprise.
                For testing, manual upgrades, and trial grants — does not create a Stripe subscription.
                Setting to "pro", "business", or "enterprise" sets period_end to now + duration_days (default 365).
                Setting to "free" clears subscription data. Use duration_days: 90 for a 3-month trial.
            parameters:
                - name: org_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/SetBillingTierRequest"
            responses:
                "200":
                    description: Billing tier updated
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"

    /v1/admin/usage/reset:
        post:
            tags: [Admin]
            summary: Reset all API usage events (testing)
            operationId: adminResetUsageEvents
            description: |
                Deletes every row in `usage_events` for all organizations. Resets monthly
                request counts used for free-tier / x402 quota. Does not change prepaid credit
                balances or Stripe. **Platform admin only** (same guard as other `/v1/admin/*` routes).
            responses:
                "200":
                    description: Usage table cleared; returns number of deleted rows
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ResetUsageEventsResponse"
                "403":
                    $ref: "#/components/responses/Forbidden"

    /v1/admin/usage/reset-for-user:
        post:
            tags: [Admin]
            summary: Reset API usage for a user's organization
            operationId: adminResetUsageForUserByEmail
            description: |
                Looks up a registered user by email and deletes all `usage_events` rows for that
                user's `org_id`. Resets free-tier / monthly quota for the whole org (not other orgs).
                **Platform admin only.**
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/ResetUsageForUserEmailRequest"
            responses:
                "200":
                    description: Usage cleared for the user's org
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ResetUsageForUserEmailResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    # ---------------------------------------------------------------------------
    # Health
    # ---------------------------------------------------------------------------

    /v1/health:
        get:
            tags: [Health]
            summary: Service health check
            operationId: healthCheck
            security: []
            responses:
                "200":
                    description: Healthy
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/HealthResponse"

    /v1/health/hsm:
        get:
            tags: [Health]
            summary: HSM connectivity check
            operationId: healthHsm
            security: []
            responses:
                "200":
                    description: HSM status
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        enum: [ok, degraded, unavailable]

    # --- Shroud Activity ---

    /v1/shroud/activity:
        get:
            tags: [Shroud]
            summary: List Shroud activity events
            description: Returns recent Shroud proxy activity for the organization (LLM requests, inspections, policy actions).
            security:
                - BearerAuth: []
            parameters:
                - in: query
                  name: agent_id
                  schema:
                      type: string
                  description: Filter by agent ID
                - in: query
                  name: action
                  schema:
                      type: string
                  description: Filter by action (allowed, blocked, warned)
                - in: query
                  name: limit
                  schema:
                      type: integer
                      default: 50
                  description: Maximum events to return
                - in: query
                  name: offset
                  schema:
                      type: integer
                      default: 0
                  description: Pagination offset
            responses:
                "200":
                    description: Activity events
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    events:
                                        type: array
                                        items:
                                            $ref: "#/components/schemas/ShroudActivityEvent"
                                    total:
                                        type: integer
                "401":
                    description: Unauthorized
        post:
            tags: [Shroud]
            summary: Ingest Shroud activity event (internal)
            description: Called by the Shroud proxy to record activity events. Not intended for external use.
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/IngestShroudActivityRequest"
            responses:
                "201":
                    description: Event recorded
                "401":
                    description: Unauthorized

    /v1/shroud/threat-summary:
        get:
            tags: [Shroud]
            summary: Shroud threat analytics summary
            description: >
                Aggregated threat metrics for the organization from `shroud_activity`
                (detectors, blocked counts, recent flagged requests). Query `period` selects
                the window; the previous window of equal length is used for request volume trend.
            security:
                - BearerAuth: []
            parameters:
                - in: query
                  name: period
                  schema:
                      type: string
                      enum: [1h, 24h, 7d, 30d]
                      default: 24h
                  description: Rolling window ending now
            responses:
                "200":
                    description: Threat summary
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ShroudThreatSummary"
                "400":
                    description: Invalid period
                "401":
                    description: Unauthorized

    # --- Platform API ---

    /v1/platform/apps:
        post:
            tags: [Platform]
            summary: Register a platform app
            description: Register a new platform app for building on top of 1Claw. Returns an API key (plt_ prefix) that must be saved immediately.
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreatePlatformAppRequest"
            responses:
                "201":
                    description: Platform app created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/PlatformAppCreatedResponse"
                "400":
                    description: Invalid request
                "403":
                    description: Only human users can register platform apps
        get:
            tags: [Platform]
            summary: List platform apps
            description: List all platform apps in the organization.
            security:
                - BearerAuth: []
            responses:
                "200":
                    description: List of platform apps
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/PlatformAppResponse"

    /v1/platform/apps/{appId}:
        get:
            tags: [Platform]
            summary: Get platform app details
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: appId
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Platform app details
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/PlatformAppResponse"
                "404":
                    description: Not found
        patch:
            tags: [Platform]
            summary: Update platform app
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: appId
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UpdatePlatformAppRequest"
            responses:
                "200":
                    description: Updated platform app
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/PlatformAppResponse"
        delete:
            tags: [Platform]
            summary: Delete platform app
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: appId
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Deleted
                "403":
                    description: Only human users can delete platform apps

    /v1/platform/apps/{appId}/rotate-key:
        post:
            tags: [Platform]
            summary: Rotate platform API key
            description: Generate a new API key for the platform app. The old key is immediately invalidated. Returns the new key (one-time).
            security:
                - BearerAuth: []
            parameters:
                - name: appId
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                api_key_expires_at:
                                    type: string
                                    format: date-time
                                    nullable: true
                                    description: Optional expiration for the new key.
            responses:
                "200":
                    description: New key generated
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    api_key:
                                        type: string
                                        description: The new API key (shown once)
                                    api_key_prefix:
                                        type: string
                                    api_key_expires_at:
                                        type: string
                                        format: date-time
                                        nullable: true
                "403":
                    description: Only human users can rotate platform keys

    /v1/platform/apps/{appId}/templates:
        post:
            tags: [Platform]
            summary: Create bootstrap template
            description: Create a template that defines what vault, agents, and policies to bootstrap for each connected user.
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: appId
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateTemplateRequest"
            responses:
                "201":
                    description: Template created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/PlatformTemplateResponse"
        get:
            tags: [Platform]
            summary: List templates
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: appId
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: List of templates
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/PlatformTemplateResponse"

    /v1/platform/users/upsert:
        post:
            tags: [Platform]
            summary: Provision or look up a platform user
            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.
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UpsertPlatformUserRequest"
            responses:
                "200":
                    description: Existing user found
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/PlatformUserResponse"
                "201":
                    description: New user created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/PlatformUserResponse"
                "409":
                    description: User exists in a different organization. Contains a link_required payload with an OAuth authorize URL for cross-org consent.
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/PlatformUserLinkRequiredResponse"

    /v1/platform/apps/{appId}/users:
        get:
            tags: [Platform]
            summary: List connected users
            description: List all users connected to this platform app.
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: appId
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Connected users
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/PlatformConnectedUserResponse"

    /v1/platform/connections/{connectionId}/bootstrap:
        post:
            tags: [Platform]
            summary: Bootstrap resources for a connected user
            description: Executes a template to create vault, agent, and policies for the connected user. Returns a claim URL and token for the user to claim their resources.
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: connectionId
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/BootstrapRequest"
            responses:
                "201":
                    description: Resources bootstrapped
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/BootstrapResponse"

    /v1/platform/connections/{connectionId}/reissue-claim:
        post:
            tags: [Platform]
            summary: Reissue a claim URL
            description: Mints a fresh 10-minute claim token for an already-bootstrapped connection without re-provisioning resources. Use when the original claim URL has expired.
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: connectionId
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: false
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                return_to:
                                    type: string
                                    description: Optional redirect URL after claim
            responses:
                "200":
                    description: New claim URL issued
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    claim_url:
                                        type: string
                                    claim_token:
                                        type: string
                                    expires_in:
                                        type: integer
                                        description: Seconds until expiry (600 = 10 min)
                                    connection_id:
                                        type: string
                                        format: uuid
                "400":
                    description: Connection not yet bootstrapped
                "404":
                    description: Connection not found

    /v1/platform/apps/{appId}/audit:
        get:
            tags: [Platform]
            summary: Platform audit log
            description: Returns audit events related to this platform app.
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: appId
                  required: true
                  schema:
                      type: string
                      format: uuid
                - in: query
                  name: limit
                  schema:
                      type: integer
                      default: 50
                - in: query
                  name: offset
                  schema:
                      type: integer
                      default: 0
            responses:
                "200":
                    description: Audit events
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    events:
                                        type: array
                                        items:
                                            type: object

    /v1/platform/connected-apps:
        get:
            tags: [Platform]
            summary: List connected apps (user side)
            description: Returns platform apps connected to the calling user's account.
            security:
                - BearerAuth: []
            responses:
                "200":
                    description: Connected apps
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    connected_apps:
                                        type: array
                                        items:
                                            $ref: "#/components/schemas/ConnectedAppResponse"

    /v1/platform/connected-apps/{connectionId}:
        delete:
            tags: [Platform]
            summary: Disconnect a platform app
            description: Disconnect the calling user from a platform app.
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: connectionId
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Disconnected
                "404":
                    description: Connection not found

    /v1/platform/connections/{connectionId}/grant:
        post:
            tags: [Platform]
            summary: Grant platform app access to vaults/agents
            description: |
                User-authenticated. Grant the platform app access to selected vaults and agents.
                Validates user ownership of all requested resources. Creates platform_user_grants
                entries and merges resource IDs into the connection record.
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: connectionId
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/GrantResourcesRequest"
            responses:
                "201":
                    description: Grants created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/GrantResourcesResponse"
                "400":
                    description: No vault_ids or agent_ids provided
                "403":
                    description: Resource not owned by caller
                "404":
                    description: Connection not found

    /v1/platform/connections/{connectionId}/grants:
        get:
            tags: [Platform]
            summary: List active resource grants for a connection
            description: User-authenticated. Returns active (non-revoked) grants for the connection.
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: connectionId
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Grant list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/GrantListResponse"
                "404":
                    description: Connection not found

    /v1/platform/connections/{connectionId}/grants/{grantId}:
        delete:
            tags: [Platform]
            summary: Revoke a resource grant
            description: User-authenticated. Revoke a specific resource grant by ID.
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: connectionId
                  required: true
                  schema:
                      type: string
                      format: uuid
                - in: path
                  name: grantId
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Grant revoked
                "404":
                    description: Grant not found or already revoked

    /v1/platform/claim/{token}:
        get:
            tags: [Platform]
            summary: Preview a claim token
            description: |
                Verify a claim token and preview what was provisioned (app name, vaults, agents, policies).
                Public endpoint — the token itself is the authentication.
            parameters:
                - in: path
                  name: token
                  required: true
                  schema:
                      type: string
                  description: The `ct_` prefixed claim token from the bootstrap response
            responses:
                "200":
                    description: Claim preview
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ClaimPreviewResponse"
                "404":
                    description: Invalid or expired claim token
        post:
            tags: [Platform]
            summary: Redeem a claim token
            description: |
                Redeem a one-time claim token, marking the connection as claimed.
                Public endpoint — the token itself is the authentication. Returns 409 if already claimed, 410 if expired.
            parameters:
                - in: path
                  name: token
                  required: true
                  schema:
                      type: string
                  description: The `ct_` prefixed claim token from the bootstrap response
            responses:
                "200":
                    description: Claim redeemed
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ClaimRedeemResponse"
                "404":
                    description: Invalid claim token
                "409":
                    description: Claim token already used
                "410":
                    description: Claim token has expired

    # --- Spend Policies ---

    /v1/platform/apps/{appId}/spend-policies:
        post:
            tags: [Platform]
            summary: Create wallet spend policy
            description: |
                Create an app-wide spend policy that governs what embedded wallet users
                can do with their wallets. Policies apply to all connected users by default
                and can be overridden per-user via connection-level policies.
            operationId: createSpendPolicy
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: appId
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateSpendPolicyRequest"
            responses:
                "201":
                    description: Spend policy created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SpendPolicyResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"
        get:
            tags: [Platform]
            summary: List spend policies for app
            description: Returns all spend policies configured for the platform app.
            operationId: listSpendPolicies
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: appId
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Spend policies
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    policies:
                                        type: array
                                        items:
                                            $ref: "#/components/schemas/SpendPolicyResponse"

    /v1/platform/apps/{appId}/spend-policies/{policyId}:
        delete:
            tags: [Platform]
            summary: Delete a spend policy
            operationId: deleteSpendPolicy
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: appId
                  required: true
                  schema:
                      type: string
                      format: uuid
                - in: path
                  name: policyId
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Deleted
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/platform/connections/{connectionId}/spend-policy:
        put:
            tags: [Platform]
            summary: Set per-user spend policy override
            description: |
                Override the app-wide spend policy for a specific connected user. This
                policy takes precedence over the app default. Remove by deleting the
                connection-level policy.
            operationId: setUserSpendPolicy
            security:
                - BearerAuth: []
            parameters:
                - in: path
                  name: connectionId
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateSpendPolicyRequest"
            responses:
                "200":
                    description: Spend policy set
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SpendPolicyResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"

    # --- Approvals ---

    /v1/approvals:
        get:
            tags: [Approvals]
            summary: List pending approvals
            description: |
                Returns approvals for the authenticated user's organization.
                Human-only. Supports filtering by status and pagination.
            operationId: listApprovals
            parameters:
                - name: status
                  in: query
                  required: false
                  schema:
                      type: string
                      enum: [pending, approved, rejected, expired]
                  description: Filter by approval status
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      default: 50
                - name: offset
                  in: query
                  required: false
                  schema:
                      type: integer
                      default: 0
            responses:
                "200":
                    description: Approval list
                    content:
                        application/json:
                            schema:
                                type: object
                                required: [approvals]
                                properties:
                                    approvals:
                                        type: array
                                        items:
                                            $ref: "#/components/schemas/ApprovalResponse"

    /v1/approvals/{approval_id}:
        get:
            tags: [Approvals]
            summary: Get approval details
            description: Returns details for a single approval by ID.
            operationId: getApproval
            parameters:
                - name: approval_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Approval details
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ApprovalResponse"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/approvals/{approval_id}/decide:
        post:
            tags: [Approvals]
            summary: Approve or reject
            description: |
                Submit a decision (approve or reject) for a pending approval.
                Human-only. The approval must be in `pending` status.
                For `card_order` approvals, approving auto-executes the x402 payment;
                rejecting marks the card as `rejected`.
                Risk tier 2+ approvals require step-up authentication via
                `X-Auth-Confirm` (account password or `rat_` re-auth token from
                `POST /v1/auth/reauth/begin` + `complete`). Risk tier 3 requires
                passkey or TOTP re-auth token.
            operationId: decideApproval
            parameters:
                - name: approval_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/DecideApprovalRequest"
            responses:
                "200":
                    description: Decision recorded
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ApprovalResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "404":
                    $ref: "#/components/responses/NotFound"
                "409":
                    $ref: "#/components/responses/Conflict"

    /v1/approvals/quick-decide:
        get:
            tags: [Approvals]
            summary: One-click approve or deny (email link)
            description: |
                Public endpoint (no Bearer auth). The `token` query param is the
                authenticator — SHA-256 hashed, single-use, 7-day TTL. On success
                redirects to `{public_url}/approvals/{id}?decided=true`.
                Auto-executes approved `card_order` and `policy_change` actions.
            operationId: quickDecideApproval
            parameters:
                - name: token
                  in: query
                  required: true
                  schema:
                      type: string
                - name: decision
                  in: query
                  required: true
                  schema:
                      type: string
                      enum: [approved, rejected]
            responses:
                "302":
                    description: Redirect to dashboard confirmation page
                "400":
                    $ref: "#/components/responses/BadRequest"
                "404":
                    $ref: "#/components/responses/NotFound"
                "409":
                    $ref: "#/components/responses/Conflict"

    /v1/deposit-destinations:
        post:
            tags: [Treasury]
            summary: Create deposit destination
            operationId: createDepositDestination
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [chain]
                            properties:
                                chain: { type: string }
                                label: { type: string }
                                treasury_wallet_id: { type: string, format: uuid }
            responses:
                "201":
                    description: Destination created
                "401":
                    $ref: "#/components/responses/Unauthorized"
        get:
            tags: [Treasury]
            summary: List deposit destinations
            operationId: listDepositDestinations
            security:
                - BearerAuth: []
            responses:
                "200":
                    description: List of destinations

    /v1/deposit-destinations/{id}:
        get:
            tags: [Treasury]
            summary: Get deposit destination
            operationId: getDepositDestination
            security:
                - BearerAuth: []
            parameters:
                - name: id
                  in: path
                  required: true
                  schema: { type: string, format: uuid }
            responses:
                "200":
                    description: Destination detail with events
        patch:
            tags: [Treasury]
            summary: Update deposit destination status
            operationId: updateDepositDestination
            security:
                - BearerAuth: []
            parameters:
                - name: id
                  in: path
                  required: true
                  schema: { type: string, format: uuid }
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                status: { type: string, enum: [active, paused, archived] }
            responses:
                "200":
                    description: Updated destination

    /v1/internal-accounts:
        post:
            tags: [Treasury]
            summary: Create internal account
            operationId: createInternalAccount
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [name]
                            properties:
                                name: { type: string }
                                description: { type: string }
            responses:
                "201":
                    description: Account created
        get:
            tags: [Treasury]
            summary: List internal accounts
            operationId: listInternalAccounts
            security:
                - BearerAuth: []
            responses:
                "200":
                    description: Account list with balances

    /v1/internal-accounts/{id}:
        get:
            tags: [Treasury]
            summary: Get internal account
            operationId: getInternalAccount
            security:
                - BearerAuth: []
            parameters:
                - name: id
                  in: path
                  required: true
                  schema: { type: string, format: uuid }
            responses:
                "200":
                    description: Account detail

    /v1/internal-accounts/{id}/ledger:
        get:
            tags: [Treasury]
            summary: Get account ledger
            operationId: getInternalAccountLedger
            security:
                - BearerAuth: []
            parameters:
                - name: id
                  in: path
                  required: true
                  schema: { type: string, format: uuid }
            responses:
                "200":
                    description: Ledger entries

    /v1/internal-transfers:
        post:
            tags: [Treasury]
            summary: Transfer between internal accounts
            operationId: createInternalTransfer
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [from_account_id, to_account_id, asset, amount]
                            properties:
                                from_account_id: { type: string, format: uuid }
                                to_account_id: { type: string, format: uuid }
                                asset: { type: string }
                                amount: { type: string }
                                memo: { type: string }
            responses:
                "201":
                    description: Transfer completed

    /v1/fiat/onramp/session:
        post:
            tags: [Billing]
            summary: Create fiat onramp session
            operationId: createFiatOnrampSession
            security:
                - BearerAuth: []
            responses:
                "201":
                    description: Onramp widget URL

    /v1/fiat/offramp/initiate:
        post:
            tags: [Billing]
            summary: Initiate fiat offramp
            operationId: initiateFiatOfframp
            security:
                - BearerAuth: []
            responses:
                "201":
                    description: Offramp widget URL

    /v1/auth/social-login:
        post:
            tags: [Authentication]
            summary: Social login (Google, Apple, Discord)
            operationId: socialLogin
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [provider, id_token]
                            properties:
                                provider: { type: string, enum: [google, apple, discord] }
                                id_token:
                                    type: string
                                    description: Google/Apple ID token, or Discord OAuth authorization code
                                oauth_redirect_uri:
                                    type: string
                                    description: Required for Discord — must match the redirect URI used in the OAuth flow
                                auto_provision_chains:
                                    type: array
                                    items: { type: string }
            responses:
                "200":
                    description: Login successful
                "201":
                    description: New user created
                "409":
                    description: Email already registered (no auto-linking)
                "401":
                    description: Invalid or unverified token

    /v1/auth/passkeys/tx-assert/begin:
        post:
            tags: [Authentication]
            summary: Begin passkey transaction authorization
            description: |
                Requires `tx_digest` — SHA-256 hex of canonical `chain|to|value_wei|data`
                for the treasury send being authorized. The server recomputes this digest
                on send and rejects passkey tokens that do not match.
            operationId: passkeyTxAssertBegin
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [tx_digest]
                            properties:
                                tx_digest:
                                    type: string
                                    description: 64-char hex SHA-256 of canonical send params
            responses:
                "200":
                    description: WebAuthn challenge
                "400":
                    description: Missing or invalid tx_digest

    /v1/auth/passkeys/tx-assert/complete:
        post:
            tags: [Authentication]
            summary: Complete passkey transaction authorization
            operationId: passkeyTxAssertComplete
            security:
                - BearerAuth: []
            responses:
                "200":
                    description: Passkey token for X-Passkey-Token header

    # ---------------------------------------------------------------------------
    # Email OTP
    # ---------------------------------------------------------------------------

    /v1/auth/email-otp/send:
        post:
            tags: [Authentication]
            summary: Send email OTP code
            description: |
                Sends a 6-digit one-time code to the specified email address.
                No authentication required. Rate-limited per IP and per email.
            operationId: sendEmailOtp
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [email]
                            properties:
                                email:
                                    type: string
                                    format: email
                                platform_app_id:
                                    type: string
                                    format: uuid
                                    description: Optional platform app context for embedded wallet flows
            responses:
                "200":
                    description: OTP sent
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        enum: [sent]
                "429":
                    description: Rate limited

    /v1/auth/email-otp/verify:
        post:
            tags: [Authentication]
            summary: Verify email OTP and get JWT
            description: |
                Verifies the 6-digit code sent to the user's email. If the user does not
                exist, a new account is created. Optionally auto-provisions treasury wallets
                for the specified chains. Returns a JWT for subsequent API calls.
            operationId: verifyEmailOtp
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [email, code]
                            properties:
                                email:
                                    type: string
                                    format: email
                                code:
                                    type: string
                                    description: 6-digit OTP code
                                platform_app_id:
                                    type: string
                                    format: uuid
                                auto_provision_chains:
                                    type: array
                                    items: { type: string }
                                    description: Chains to auto-generate wallets for (e.g. ["ethereum", "base"])
            responses:
                "200":
                    description: Existing user authenticated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/EmailOtpVerifyResponse"
                "201":
                    description: New user created and authenticated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/EmailOtpVerifyResponse"
                "400":
                    description: Invalid or expired code
                "429":
                    description: Rate limited

    # ---------------------------------------------------------------------------
    # OAuth
    # ---------------------------------------------------------------------------

    /v1/oauth/authorize:
        get:
            tags: [OAuth]
            summary: Get OAuth consent info
            description: |
                Returns information about the platform app requesting authorization so the
                UI can display a consent screen. Used by the 1Claw-hosted consent page.
            operationId: getOAuthConsent
            security:
                - BearerAuth: []
            parameters:
                - name: client_id
                  in: query
                  required: true
                  schema: { type: string }
                  description: Platform app slug
                - name: redirect_uri
                  in: query
                  required: true
                  schema: { type: string, format: uri }
                - name: response_type
                  in: query
                  required: true
                  schema: { type: string, enum: [code] }
                - name: scope
                  in: query
                  schema: { type: string }
                  description: Space-delimited scopes (e.g. "openid email wallet")
                - name: state
                  in: query
                  schema: { type: string }
                - name: code_challenge
                  in: query
                  schema: { type: string }
                  description: PKCE code challenge
                - name: code_challenge_method
                  in: query
                  schema: { type: string, enum: [S256, plain] }
                - name: nonce
                  in: query
                  schema: { type: string }
                  description: OIDC nonce for ID token replay protection
            responses:
                "200":
                    description: Consent screen data
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/OAuthConsentResponse"
                "400":
                    description: Invalid client_id, redirect_uri, or response_type
        post:
            tags: [OAuth]
            summary: Submit OAuth consent decision
            description: |
                The user approves or denies the authorization request. On approval, returns
                a redirect URL containing the authorization code. On denial, returns a
                redirect URL with an error parameter.
            operationId: submitOAuthConsent
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [approve, client_id, redirect_uri]
                            properties:
                                approve: { type: boolean }
                                client_id: { type: string }
                                redirect_uri: { type: string, format: uri }
                                scope: { type: string }
                                state: { type: string }
                                code_challenge: { type: string }
                                code_challenge_method: { type: string, enum: [S256, plain] }
                                nonce: { type: string }
            responses:
                "200":
                    description: Redirect URL with authorization code or error
                    content:
                        application/json:
                            schema:
                                type: object
                                required: [redirect_url]
                                properties:
                                    redirect_url:
                                        type: string
                                        format: uri
                "400":
                    description: Invalid request

    /v1/oauth/token:
        post:
            tags: [OAuth]
            summary: Exchange authorization code for tokens
            description: |
                Standard OAuth 2.0 token endpoint. Exchanges an authorization code for an
                access token and optional OIDC ID token. Supports PKCE via `code_verifier`.
            operationId: exchangeOAuthToken
            security: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [grant_type, code, client_id, redirect_uri]
                            properties:
                                grant_type:
                                    type: string
                                    enum: [authorization_code]
                                code: { type: string }
                                client_id: { type: string }
                                redirect_uri: { type: string, format: uri }
                                code_verifier:
                                    type: string
                                    description: PKCE code verifier (required when code_challenge was used)
            responses:
                "200":
                    description: Token response
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/OAuthTokenResponse"
                "400":
                    description: Invalid grant, code, or verifier
                "401":
                    description: Invalid client credentials

    /v1/oauth/userinfo:
        get:
            tags: [OAuth]
            summary: Get authenticated user info (OIDC UserInfo)
            description: |
                Standard OIDC UserInfo endpoint. Returns claims about the authenticated user
                based on the granted scopes.
            operationId: getOAuthUserInfo
            security:
                - BearerAuth: []
            responses:
                "200":
                    description: User info
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/OAuthUserInfoResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"

    # ---------------------------------------------------------------------------
    # Risk Engine
    # ---------------------------------------------------------------------------

    /v1/risk/events:
        get:
            tags: [Risk Engine]
            summary: List risk events
            description: |
                Returns risk events detected by the risk engine, ordered by most recent first.
                Filter by severity or principal type.
            operationId: listRiskEvents
            parameters:
                - name: severity
                  in: query
                  schema:
                      type: string
                      enum: [low, medium, high, critical]
                  description: Filter events by severity level
                - name: principal_type
                  in: query
                  schema:
                      type: string
                      enum: [user, agent]
                  description: Filter events by principal type
                - name: limit
                  in: query
                  schema:
                      type: integer
                      default: 50
                - name: offset
                  in: query
                  schema:
                      type: integer
                      default: 0
            responses:
                "200":
                    description: Risk event list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/RiskEventListResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"

    /v1/risk/verdicts:
        get:
            tags: [Risk Engine]
            summary: List risk verdicts
            description: Returns all active risk verdicts for the caller's organization.
            operationId: listRiskVerdicts
            responses:
                "200":
                    description: Verdict list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/RiskVerdictListResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"

    /v1/risk/verdicts/{principal_type}/{principal_id}:
        get:
            tags: [Risk Engine]
            summary: Get risk verdict for a principal
            description: Returns the current risk verdict for a specific user or agent.
            operationId: getRiskVerdict
            parameters:
                - name: principal_type
                  in: path
                  required: true
                  schema:
                      type: string
                      enum: [user, agent]
                - name: principal_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Risk verdict (null if no verdict exists)
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    verdict:
                                        $ref: "#/components/schemas/RiskVerdict"
                                        nullable: true
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/risk/honeytokens:
        get:
            tags: [Risk Engine]
            summary: List honeytokens
            description: Returns all honeytokens (canary secrets) configured for the caller's organization.
            operationId: listHoneytokens
            responses:
                "200":
                    description: Honeytoken list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/HoneytokenListResponse"
                "401":
                    $ref: "#/components/responses/Unauthorized"
        post:
            tags: [Risk Engine]
            summary: Create a honeytoken
            description: |
                Register a secret path as a honeytoken (canary). Any access to this secret
                triggers a risk event and increments the trigger counter.
            operationId: createHoneytoken
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateHoneytokenRequest"
            responses:
                "201":
                    description: Honeytoken created
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    honeytoken:
                                        $ref: "#/components/schemas/Honeytoken"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "401":
                    $ref: "#/components/responses/Unauthorized"

    /v1/risk/honeytokens/{id}:
        delete:
            tags: [Risk Engine]
            summary: Delete a honeytoken
            description: Remove a honeytoken registration. The underlying secret is not affected.
            operationId: deleteHoneytoken
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Honeytoken deleted
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    deleted:
                                        type: boolean
                "401":
                    $ref: "#/components/responses/Unauthorized"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/tokens:
        get:
            tags: [Tokens]
            summary: List known tokens
            operationId: listKnownTokens
            parameters:
                - name: chain
                  in: query
                  schema:
                      type: string
                  description: Filter by chain name
            responses:
                "200":
                    description: Token list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/KnownTokenListResponse"

    /v1/chains/{chain_name}/tokens:
        get:
            tags: [Tokens]
            summary: List tokens for a specific chain
            operationId: listTokensByChain
            parameters:
                - name: chain_name
                  in: path
                  required: true
                  schema:
                      type: string
            responses:
                "200":
                    description: Token list for chain
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/KnownTokenListResponse"

    /v1/admin/tokens:
        post:
            tags: [Admin, Tokens]
            summary: Create a known token (admin only)
            operationId: createKnownToken
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CreateKnownTokenRequest"
            responses:
                "201":
                    description: Token created
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/KnownToken"
                "403":
                    $ref: "#/components/responses/Forbidden"

    /v1/admin/tokens/{token_id}:
        delete:
            tags: [Admin, Tokens]
            summary: Delete a known token (admin only)
            operationId: deleteKnownToken
            security:
                - BearerAuth: []
            parameters:
                - name: token_id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "204":
                    description: Token deleted
                "403":
                    $ref: "#/components/responses/Forbidden"

    /v1/agents/{agent_id}/cards/order:
        post:
            tags: [Payment Cards]
            summary: Order a payment card (x402)
            description: >
                Order a prepaid or gift card for an agent. Drives the x402
                payment flow server-side using the agent's Ethereum signing key
                (funded with USDC on Base). Requires `cards_enabled` on the agent
                and a Pro or higher plan. An `Idempotency-Key` header is required.
                When `card_require_approval` is true (default), the order is held
                in `awaiting_approval` until a human approves via the dashboard,
                mobile app, or email one-click link; payment runs only after approval.
            operationId: orderCard
            parameters:
                - $ref: "#/components/parameters/AgentId"
                - name: Idempotency-Key
                  in: header
                  required: true
                  schema:
                      type: string
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/OrderCardRequest"
            responses:
                "202":
                    description: Card order queued for human approval (status awaiting_approval)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CardResponse"
                "201":
                    description: Card order accepted and payment submitted (status pending)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CardResponse"
                "200":
                    description: Idempotent replay of a prior order
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CardResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "409":
                    $ref: "#/components/responses/Conflict"

    /v1/cards:
        get:
            tags: [Payment Cards]
            summary: List payment cards
            description: List cards for the caller (agents see only their own). Always masked (last4 only).
            operationId: listCards
            responses:
                "200":
                    description: Card list
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CardListResponse"

    /v1/cards/import:
        post:
            tags: [Payment Cards]
            summary: Import a card (human-only)
            description: Manually import an existing card. Full storage mode — PAN stored encrypted, CVV as a one-time-read secret. Human-only.
            operationId: importCard
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/ImportCardRequest"
            responses:
                "201":
                    description: Card imported
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CardResponse"
                "400":
                    $ref: "#/components/responses/BadRequest"
                "403":
                    $ref: "#/components/responses/Forbidden"

    /v1/cards/gift-cards/search:
        post:
            tags: [Payment Cards]
            summary: Search gift-card brands
            description: Search available Laso gift-card brands/servers for the org's Laso account.
            operationId: searchGiftCards
            requestBody:
                required: false
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/SearchGiftCardsRequest"
            responses:
                "200":
                    description: Available gift-card brands (provider-shaped payload)
                    content:
                        application/json:
                            schema:
                                type: object
                                additionalProperties: true

    /v1/cards/{card_id}:
        get:
            tags: [Payment Cards]
            summary: Get a payment card
            description: Get a single card (masked — last4 only).
            operationId: getCard
            parameters:
                - $ref: "#/components/parameters/CardId"
            responses:
                "200":
                    description: Card details
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CardResponse"
                "404":
                    $ref: "#/components/responses/NotFound"
        patch:
            tags: [Payment Cards]
            summary: Update a card's reveal policy (human-only)
            operationId: updateCard
            parameters:
                - $ref: "#/components/parameters/CardId"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UpdateCardRequest"
            responses:
                "200":
                    description: Card updated
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CardResponse"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/cards/{card_id}/reveal:
        post:
            tags: [Payment Cards]
            summary: Reveal card details
            description: >
                Reveal full card details (PAN/CVV or gift-card redemption).
                Humans must re-authenticate with their account password via the
                `X-Auth-Confirm` header. Agents may reveal only when a human has
                enabled a per-card reveal policy. Once revealed, the card can be
                used anywhere up to its balance — 1Claw has no further control.
            operationId: revealCard
            parameters:
                - $ref: "#/components/parameters/CardId"
                - name: X-Auth-Confirm
                  in: header
                  required: false
                  description: Account password (humans) for re-authentication.
                  schema:
                      type: string
            responses:
                "200":
                    description: Revealed card details (sensitive)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CardRevealResponse"
                "403":
                    $ref: "#/components/responses/Forbidden"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/cards/{card_id}/void:
        post:
            tags: [Payment Cards]
            summary: Void a card
            description: 1Claw-level lock that blocks all further reveals/refreshes. Forward-looking only — a card revealed before void remains live.
            operationId: voidCard
            parameters:
                - $ref: "#/components/parameters/CardId"
            responses:
                "200":
                    description: Card voided
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CardResponse"
                "404":
                    $ref: "#/components/responses/NotFound"

    /v1/cards/{card_id}/refresh:
        post:
            tags: [Payment Cards]
            summary: Refresh a card's balance
            description: Proxy Laso refresh to update balance/status. Rate-limited to once per 5 minutes per card (429 on exceed).
            operationId: refreshCard
            parameters:
                - $ref: "#/components/parameters/CardId"
            responses:
                "200":
                    description: Card refreshed
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CardResponse"
                "429":
                    description: Refreshed too recently
                "404":
                    $ref: "#/components/responses/NotFound"

# =============================================================================
# COMPONENTS
# =============================================================================

components:
    securitySchemes:
        BearerAuth:
            type: http
            scheme: bearer
            bearerFormat: JWT
        ApiKeyAuth:
            type: http
            scheme: bearer
            description: 1ck_ prefixed API key used as Bearer token

    parameters:
        VaultId:
            name: vault_id
            in: path
            required: true
            schema:
                type: string
                format: uuid
        SecretPath:
            name: path
            in: path
            required: true
            schema:
                type: string
            description: Secret path (e.g. "db/credentials")
        AgentId:
            name: agent_id
            in: path
            required: true
            schema:
                type: string
                format: uuid
        PolicyId:
            name: policy_id
            in: path
            required: true
            schema:
                type: string
                format: uuid
        CardId:
            name: card_id
            in: path
            required: true
            schema:
                type: string
                format: uuid
        IncludeSignedTx:
            name: include_signed_tx
            in: query
            required: false
            description: >
                Set to `true` or `1` to include the raw signed transaction hex in the response.
                Omitted by default to reduce key exfiltration risk. Only the literal values "true" or "1" enable inclusion; any other value or omission returns responses without signed_tx.
                Applies to GET /v1/agents/{agent_id}/transactions and GET /v1/agents/{agent_id}/transactions/{tx_id}.
            schema:
                type: boolean
                default: false
                example: false

    responses:
        BadRequest:
            description: Invalid request
            content:
                application/json:
                    schema:
                        $ref: "#/components/schemas/ProblemDetails"
        Unauthorized:
            description: Authentication required or invalid
            content:
                application/json:
                    schema:
                        $ref: "#/components/schemas/ProblemDetails"
        Forbidden:
            description: Insufficient permissions
            content:
                application/json:
                    schema:
                        $ref: "#/components/schemas/ProblemDetails"
        NotFound:
            description: Resource not found
            content:
                application/json:
                    schema:
                        $ref: "#/components/schemas/ProblemDetails"
        PaymentRequired:
            description: x402 payment required
            content:
                application/json:
                    schema:
                        $ref: "#/components/schemas/PaymentRequirement"
        Conflict:
            description: Resource already exists or conflict
            content:
                application/json:
                    schema:
                        $ref: "#/components/schemas/ProblemDetails"

    schemas:
        OrderCardRequest:
            type: object
            required: [kind, amount_usd]
            properties:
                kind:
                    type: string
                    enum: [prepaid, gift_card]
                amount_usd:
                    type: string
                    description: USD amount to load onto the card.
                    example: "25.00"
                laso_server_id:
                    type: string
                    description: Optional Laso gift-card server/brand id (gift cards only).
                country:
                    type: string
                    description: Optional country (prepaid cards; defaults to US).
        CardResponse:
            type: object
            description: Masked card view — never contains PAN/CVV.
            required: [id, issuer, kind, currency, status, storage_mode, reveal_policy, created_at, updated_at]
            properties:
                id:
                    type: string
                    format: uuid
                agent_id:
                    type: string
                    format: uuid
                    nullable: true
                issuer:
                    type: string
                    enum: [laso, manual]
                kind:
                    type: string
                    enum: [prepaid, gift_card]
                brand:
                    type: string
                last4:
                    type: string
                exp_month:
                    type: integer
                exp_year:
                    type: integer
                currency:
                    type: string
                order_amount_usd:
                    type: string
                balance:
                    type: string
                status:
                    type: string
                    enum: [ordering, pending, ready, depleted, expired, voided, orphaned_payment, awaiting_approval, rejected]
                storage_mode:
                    type: string
                    enum: [reference, full]
                reveal_policy:
                    type: object
                    additionalProperties: true
                approval_id:
                    type: string
                    format: uuid
                    description: Linked approval when status is awaiting_approval
                void_after:
                    type: string
                    format: date-time
                created_at:
                    type: string
                    format: date-time
                updated_at:
                    type: string
                    format: date-time
        CardListResponse:
            type: object
            required: [cards]
            properties:
                cards:
                    type: array
                    items:
                        $ref: "#/components/schemas/CardResponse"
        CardRevealResponse:
            type: object
            description: Revealed card details — sensitive. Returned only by the reveal endpoint.
            required: [id, disclaimer]
            properties:
                id:
                    type: string
                    format: uuid
                pan:
                    type: string
                cvv:
                    type: string
                exp_month:
                    type: integer
                exp_year:
                    type: integer
                brand:
                    type: string
                redemption:
                    type: object
                    additionalProperties: true
                    description: Gift-card redemption payload (URL/code/PIN) when applicable.
                disclaimer:
                    type: string
        UpdateCardRequest:
            type: object
            description: Human-settable per-card reveal policy + lifecycle controls.
            properties:
                agent_reveal:
                    type: boolean
                max_reveals:
                    type: integer
                reveal_expires_at:
                    type: string
                    format: date-time
                    nullable: true
                void_after:
                    type: string
                    format: date-time
                    nullable: true
        ImportCardRequest:
            type: object
            required: [pan, cvv, exp_month, exp_year]
            properties:
                pan:
                    type: string
                cvv:
                    type: string
                exp_month:
                    type: integer
                exp_year:
                    type: integer
                brand:
                    type: string
                currency:
                    type: string
                balance:
                    type: string
                agent_id:
                    type: string
                    format: uuid
        SearchGiftCardsRequest:
            type: object
            properties:
                query:
                    type: string
                country:
                    type: string
        ProblemDetails:
            type: object
            description: RFC 7807 error envelope
            properties:
                type:
                    type: string
                title:
                    type: string
                status:
                    type: integer
                detail:
                    type: string

        ResetUsageEventsResponse:
            type: object
            required: [deleted_events]
            properties:
                deleted_events:
                    type: integer
                    format: int64
                    description: Number of usage_events rows removed

        ResetUsageForUserEmailRequest:
            type: object
            required: [email]
            properties:
                email:
                    type: string
                    format: email

        ResetUsageForUserEmailResponse:
            type: object
            required:
                [deleted_events, org_id, user_id, email, display_name]
            properties:
                deleted_events:
                    type: integer
                    format: int64
                org_id:
                    type: string
                    format: uuid
                user_id:
                    type: string
                    format: uuid
                email:
                    type: string
                display_name:
                    type: string

        # --- Auth ---

        LoginRequest:
            type: object
            required: [email, password]
            properties:
                email:
                    type: string
                    format: email
                password:
                    type: string
                    format: password

        LoginResponse:
            type: object
            properties:
                access_token:
                    type: string
                token_type:
                    type: string
                expires_in:
                    type: integer
                refresh_token:
                    type: string
                mfa_required:
                    type: boolean
                mfa_token:
                    type: string

        TokenResponse:
            type: object
            required: [access_token, token_type]
            properties:
                access_token:
                    type: string
                token_type:
                    type: string
                expires_in:
                    type: integer
                refresh_token:
                    type: string

        AgentTokenRequest:
            type: object
            required: [api_key]
            properties:
                agent_id:
                    type: string
                    format: uuid
                    description: Optional when using key-only auth (ocv_ keys auto-resolve agent)
                api_key:
                    type: string

        UserApiKeyTokenRequest:
            type: object
            required: [api_key]
            properties:
                api_key:
                    type: string

        TokenExchangeRequest:
            type: object
            required: [grant_type, subject_token, subject_token_type, audience]
            description: |
                RFC 8693 token-exchange request body. `subject_token_type`
                accepts the standard JWT URI or 1claw's API-key URI:
                  - `urn:ietf:params:oauth:token-type:jwt`
                  - `urn:1claw:params:oauth:token-type:api-key`
            properties:
                grant_type:
                    type: string
                    enum:
                        - "urn:ietf:params:oauth:grant-type:token-exchange"
                subject_token:
                    type: string
                    description: 1claw JWT or `ocv_` API key authorising the exchange.
                subject_token_type:
                    type: string
                    enum:
                        - "urn:ietf:params:oauth:token-type:jwt"
                        - "urn:1claw:params:oauth:token-type:api-key"
                audience:
                    type: string
                    format: uri
                    description: Required `aud` claim for the issued federation token (must be in agent's allowlist).
                    example: "https://api.anthropic.com"
                scope:
                    type: string
                    description: Optional space-separated subset of the agent's existing scopes.
                requested_token_type:
                    type: string
                    description: Optional. Defaults to `urn:ietf:params:oauth:token-type:jwt`.

        TokenExchangeResponse:
            type: object
            required: [access_token, issued_token_type, token_type, expires_in]
            properties:
                access_token:
                    type: string
                    description: RS256-signed federation JWT.
                issued_token_type:
                    type: string
                token_type:
                    type: string
                expires_in:
                    type: integer
                scope:
                    type: string

        SignupRequest:
            type: object
            required: [email, password]
            properties:
                email:
                    type: string
                    format: email
                password:
                    type: string
                    format: password
                display_name:
                    type: string

        SignupResponse:
            type: object
            properties:
                message:
                    type: string
                email:
                    type: string
                access_token:
                    type: string
                token_type:
                    type: string

        GoogleAuthRequest:
            type: object
            required: [id_token]
            properties:
                id_token:
                    type: string

        ChangePasswordRequest:
            type: object
            required: [current_password, new_password]
            properties:
                current_password:
                    type: string
                new_password:
                    type: string

        ForgotPasswordRequest:
            type: object
            required: [email]
            properties:
                email:
                    type: string
                    format: email

        ForgotPasswordResponse:
            type: object
            required: [message, status]
            properties:
                message:
                    type: string
                status:
                    type: string
                    enum: [email_sent, no_account, social_account, invalid]
                    description: |
                        Outcome of the reset request:
                        - email_sent: password reset email dispatched
                        - no_account: no account found for the email
                        - social_account: account uses Google/SSO sign-in
                        - invalid: request was malformed

        ResetPasswordRequest:
            type: object
            required: [token, new_password]
            properties:
                token:
                    type: string
                new_password:
                    type: string

        ResetPasswordResponse:
            type: object
            properties:
                message:
                    type: string

        # --- MFA ---

        MfaStatusResponse:
            type: object
            properties:
                enabled:
                    type: boolean

        MfaSetupResponse:
            type: object
            properties:
                otpauth_uri:
                    type: string
                secret:
                    type: string

        MfaVerifySetupRequest:
            type: object
            required: [code]
            properties:
                code:
                    type: string

        MfaVerifySetupResponse:
            type: object
            properties:
                recovery_codes:
                    type: array
                    items:
                        type: string

        MfaVerifyRequest:
            type: object
            required: [code, mfa_token]
            properties:
                code:
                    type: string
                mfa_token:
                    type: string

        MfaDisableRequest:
            type: object
            properties:
                code:
                    type: string
                password:
                    type: string

        # --- Device Auth ---

        DeviceCodeRequest:
            type: object
            required: [client_id, email]
            properties:
                client_id:
                    type: string
                email:
                    type: string
                    format: email
                    description: Account email; only that user may approve the code in the dashboard.

        DeviceCodeResponse:
            type: object
            properties:
                device_code:
                    type: string
                user_code:
                    type: string
                verification_uri:
                    type: string
                    format: uri
                expires_in:
                    type: integer
                interval:
                    type: integer

        DeviceTokenRequest:
            type: object
            required: [device_code, grant_type]
            properties:
                device_code:
                    type: string
                grant_type:
                    type: string

        DeviceTokenResponse:
            type: object
            properties:
                access_token:
                    type: string
                token_type:
                    type: string
                expires_in:
                    type: integer
                error:
                    type: string
                email:
                    type: string
                user_id:
                    type: string
                org_id:
                    type: string

        DeviceApproveRequest:
            type: object
            required: [user_code]
            properties:
                user_code:
                    type: string

        UserProfileResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                email:
                    type: string
                display_name:
                    type: string
                auth_method:
                    type: string
                role:
                    type: string
                email_verified:
                    type: boolean
                marketing_emails:
                    type: boolean
                totp_enabled:
                    type: boolean
                created_at:
                    type: string
                    format: date-time

        UpdateProfileRequest:
            type: object
            properties:
                display_name:
                    type: string
                marketing_emails:
                    type: boolean

        # --- API Keys ---

        CreateApiKeyRequest:
            type: object
            required: [name]
            properties:
                name:
                    type: string
                scopes:
                    type: array
                    items:
                        type: string
                expires_at:
                    type: string
                    format: date-time

        ApiKeyResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                name:
                    type: string
                key_prefix:
                    type: string
                scopes:
                    type: array
                    items:
                        type: string
                is_active:
                    type: boolean
                created_at:
                    type: string
                    format: date-time
                expires_at:
                    type: string
                    format: date-time
                last_used_at:
                    type: string
                    format: date-time

        ApiKeyCreatedResponse:
            type: object
            properties:
                key:
                    $ref: "#/components/schemas/ApiKeyResponse"
                api_key:
                    type: string
                    description: Full key (shown once)

        ApiKeyListResponse:
            type: object
            properties:
                keys:
                    type: array
                    items:
                        $ref: "#/components/schemas/ApiKeyResponse"

        # --- Vaults ---

        CreateVaultRequest:
            type: object
            required: [name]
            properties:
                name:
                    type: string
                description:
                    type: string
                mpc_custody:
                    type: string
                    description: MPC custody mode to enable at creation (e.g. "2-of-2", "2-of-3")

        VaultResponse:
            type: object
            required: [id, name, created_at]
            properties:
                id:
                    type: string
                    format: uuid
                name:
                    type: string
                description:
                    type: string
                created_by:
                    type: string
                created_by_type:
                    type: string
                created_at:
                    type: string
                    format: date-time
                cmek_enabled:
                    type: boolean
                    description: Whether client-managed encryption is enabled
                cmek_fingerprint:
                    type: string
                    description: SHA-256 fingerprint of the CMEK key (64 hex chars)
                mpc_custody:
                    type: string
                    description: MPC custody mode (e.g. "2-of-2", "2-of-3"), absent when MPC is not enabled
                mpc_threshold:
                    type: integer
                    description: Number of shares required to reconstruct the key
                mpc_providers:
                    type: array
                    items:
                        type: string
                    description: List of MPC share providers (e.g. ["server", "client"])

        VaultListResponse:
            type: object
            properties:
                vaults:
                    type: array
                    items:
                        $ref: "#/components/schemas/VaultResponse"

        # --- CMEK ---

        EnableCmekRequest:
            type: object
            required: [fingerprint]
            properties:
                fingerprint:
                    type: string
                    description: SHA-256 hex fingerprint of the CMEK key (64 chars)

        CmekRotateRequest:
            type: object
            required: [new_fingerprint]
            properties:
                new_fingerprint:
                    type: string
                    description: SHA-256 hex fingerprint of the new CMEK key

        CmekRotationJobResponse:
            type: object
            required:
                [id, vault_id, status, total_secrets, processed, created_at]
            properties:
                id:
                    type: string
                    format: uuid
                vault_id:
                    type: string
                    format: uuid
                old_fingerprint:
                    type: string
                new_fingerprint:
                    type: string
                status:
                    type: string
                    enum: [pending, running, completed, failed]
                total_secrets:
                    type: integer
                processed:
                    type: integer
                error:
                    type: string
                started_at:
                    type: string
                    format: date-time
                completed_at:
                    type: string
                    format: date-time
                created_at:
                    type: string
                    format: date-time

        # --- MPC ---

        EnableMpcRequest:
            type: object
            required: [mpc_custody]
            properties:
                mpc_custody:
                    type: string
                    description: MPC custody mode (e.g. "2-of-2", "2-of-3")

        # --- Secrets ---

        PutSecretRequest:
            type: object
            required: [value]
            properties:
                type:
                    type: string
                    description: Secret type (generic, password, api_key, certificate, private_key, ssh_key, env)
                    default: generic
                value:
                    type: string
                metadata:
                    type: object
                    additionalProperties: true
                expires_at:
                    type: string
                    format: date-time
                rotation_policy:
                    type: object
                    additionalProperties: true
                max_access_count:
                    type: integer

        SecretMetadataResponse:
            type: object
            required: [id, path, type, version, created_at]
            properties:
                id:
                    type: string
                    format: uuid
                path:
                    type: string
                type:
                    type: string
                version:
                    type: integer
                metadata:
                    type: object
                    additionalProperties: true
                created_at:
                    type: string
                    format: date-time
                expires_at:
                    type: string
                    format: date-time
                is_disabled:
                    type: boolean
                    description: Whether this version has been disabled (retained for audit but unreadable)

        SecretCreatedResponse:
            description: Returned when a secret is created or updated. Extends SecretMetadataResponse with an optional client_share for MPC vaults.
            type: object
            required: [id, path, type, version, created_at]
            properties:
                id:
                    type: string
                    format: uuid
                path:
                    type: string
                type:
                    type: string
                version:
                    type: integer
                metadata:
                    type: object
                    additionalProperties: true
                created_at:
                    type: string
                    format: date-time
                expires_at:
                    type: string
                    format: date-time
                client_share:
                    type: string
                    description: Base64-encoded client key share. Returned only for MPC 2-of-2 vaults. The client must store this share securely — it is not persisted server-side.

        SecretResponse:
            type: object
            required: [id, path, type, value, version, created_at]
            properties:
                id:
                    type: string
                    format: uuid
                path:
                    type: string
                type:
                    type: string
                value:
                    type: string
                version:
                    type: integer
                metadata:
                    type: object
                    additionalProperties: true
                created_by:
                    type: string
                created_at:
                    type: string
                    format: date-time
                expires_at:
                    type: string
                    format: date-time
                cmek_encrypted:
                    type: boolean
                    description: Whether this secret value is CMEK-encrypted (requires client-side decryption)

        SecretListResponse:
            type: object
            properties:
                secrets:
                    type: array
                    items:
                        $ref: "#/components/schemas/SecretMetadataResponse"

        SecretVersionListResponse:
            type: object
            properties:
                versions:
                    type: array
                    items:
                        $ref: "#/components/schemas/SecretMetadataResponse"

        RotateSecretRequest:
            type: object
            properties:
                length:
                    type: integer
                    minimum: 8
                    maximum: 1024
                    description: Length of the generated value (default 32)
                charset:
                    type: string
                    enum: [hex, base64, alphanumeric, ascii]
                    description: Character set for the generated value (default hex)
                type:
                    type: string
                    description: Override the secret type (defaults to existing secret's type)

        # --- Policies ---

        CreatePolicyRequest:
            type: object
            required:
                [secret_path_pattern, principal_type, principal_id, permissions]
            properties:
                secret_path_pattern:
                    type: string
                principal_type:
                    type: string
                    enum: [user, agent]
                principal_id:
                    type: string
                permissions:
                    type: array
                    items:
                        type: string
                conditions:
                    type: object
                    additionalProperties: true
                expires_at:
                    type: string
                    format: date-time

        UpdatePolicyRequest:
            type: object
            properties:
                permissions:
                    type: array
                    items:
                        type: string
                conditions:
                    type: object
                    additionalProperties: true
                expires_at:
                    type: string
                    format: date-time

        PolicyResponse:
            type: object
            required:
                [
                    id,
                    vault_id,
                    secret_path_pattern,
                    principal_type,
                    principal_id,
                    permissions,
                    created_at,
                ]
            properties:
                id:
                    type: string
                    format: uuid
                vault_id:
                    type: string
                    format: uuid
                secret_path_pattern:
                    type: string
                principal_type:
                    type: string
                principal_id:
                    type: string
                permissions:
                    type: array
                    items:
                        type: string
                conditions:
                    type: object
                    additionalProperties: true
                expires_at:
                    type: string
                    format: date-time
                created_by:
                    type: string
                created_by_type:
                    type: string
                created_at:
                    type: string
                    format: date-time

        PolicyListResponse:
            type: object
            properties:
                policies:
                    type: array
                    items:
                        $ref: "#/components/schemas/PolicyResponse"

        # --- Agent Enrollment ---

        EnrollAgentRequest:
            type: object
            required: [name]
            properties:
                name:
                    type: string
                    description: Display name for the new agent
                human_email:
                    type: string
                    format: email
                    description: |
                        Optional. If set, pending enrollment is bound to that 1Claw account email
                        and Allow/Deny links are emailed. If omitted, only `approval_url` is used
                        (link-only enrollment; human must open the URL while signed in).
                description:
                    type: string
                    description: Optional agent description

        EnrollAgentResponse:
            type: object
            properties:
                agent_id:
                    type: string
                    format: uuid
                    description: UUID of the created agent (nil UUID until approved — uniform response)
                message:
                    type: string
                    description: Status message (worded to limit email enumeration where applicable)
                approval_url:
                    type: string
                    format: uri
                    description: |
                        Present when a pending enrollment was created and the client should show
                        this link (email flow includes it as a fallback; name-only flow requires it).

        # --- Agents ---

        CreateAgentRequest:
            type: object
            required: [name]
            properties:
                name:
                    type: string
                description:
                    type: string
                auth_method:
                    type: string
                    enum: [api_key, mtls, oidc_client_credentials]
                    default: api_key
                    description: Authentication method. api_key generates a one-time key; mtls requires client_cert_fingerprint; oidc_client_credentials requires oidc_issuer and oidc_client_id.
                scopes:
                    type: array
                    items:
                        type: string
                expires_at:
                    type: string
                    format: date-time
                intents_api_enabled:
                    type: boolean
                    default: false
                tx_to_allowlist:
                    type: array
                    items:
                        type: string
                tx_max_value:
                    type: string
                    description: Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX).
                tx_daily_limit:
                    type: string
                    description: Rolling daily spend cap in native major units, enforced per chain family at signing time.
                tx_max_value_eth:
                    type: string
                    deprecated: true
                    description: Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only).
                tx_daily_limit_eth:
                    type: string
                    deprecated: true
                    description: Deprecated alias for tx_daily_limit.
                tx_allowed_chains:
                    type: array
                    items:
                        type: string
                token_ttl_seconds:
                    type: integer
                    nullable: true
                    description: Per-agent token TTL in seconds (overrides global default)
                vault_ids:
                    type: array
                    items:
                        type: string
                        format: uuid
                    description: Restrict agent to specific vault UUIDs (empty = all vaults in org)
                client_cert_fingerprint:
                    type: string
                    description: SHA-256 fingerprint of the client certificate (required for mTLS auth)
                oidc_issuer:
                    type: string
                    description: OIDC issuer URL (required for oidc_client_credentials auth)
                oidc_client_id:
                    type: string
                    description: OIDC client ID (required for oidc_client_credentials auth)
                shroud_enabled:
                    type: boolean
                    default: false
                    description: Enable Shroud LLM Proxy for this agent
                shroud_config:
                    $ref: "#/components/schemas/ShroudConfig"
                execution_intents_enabled:
                    type: boolean
                    default: false
                    description: Enable Execution Intents (bindings and execute endpoint) for this agent
                execution_guardrails:
                    type: object
                    additionalProperties: true
                    description: Guardrails applied to all execution intents for this agent
                intents_require_tee:
                    type: boolean
                    default: false
                    description: When true, transaction/sign requests must arrive via a TEE host (Pro+ only)
                execution_require_tee:
                    type: boolean
                    default: false
                    description: When true, execute requests must arrive via TEE and all direct secret reads are blocked (Pro+ only)
                tx_token_allowlist:
                    type: array
                    items:
                        type: string
                    description: Token contract/mint addresses this agent may interact with. Empty = unrestricted.
                tx_known_tokens_only:
                    type: boolean
                    default: false
                    description: When true, only tokens in the known_tokens registry may be used.
                xrpl_allowed_tx_types:
                    type: array
                    items:
                        type: string
                    description: Allowed XRP Ledger transaction types (Payment, TrustSet, etc.). Empty = all allowed.
                per_chain_guardrails:
                    type: object
                    additionalProperties: true
                    description: |
                        Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron).
                        Each value may include max_value, daily_limit, to_allowlist, token_allowlist, max_per_day, overhead_budget, max_ata_creates_per_day.
                        Strictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.
                tx_max_per_day:
                    type: integer
                    nullable: true
                    description: Max transactions per UTC calendar day. Null = unlimited.
                tx_overhead_budget:
                    type: object
                    nullable: true
                    additionalProperties:
                        type: string
                    description: Per-chain daily overhead budget in native units (e.g. {"solana":"0.5","xrp":"100"}).
                solana_ata_allowlist:
                    type: array
                    items:
                        type: string
                    description: Solana wallet addresses whose ATAs may be created. Empty = unrestricted.
                cards_enabled:
                    type: boolean
                    description: Whether this agent may order payment cards (x402 card ordering). Pro+ tier.
                card_max_order_usd:
                    type: string
                    description: Maximum USD amount for a single card order.
                card_daily_limit_usd:
                    type: string
                    description: Maximum cumulative USD spent ordering cards per rolling 24h window.
                card_payto_allowlist:
                    type: array
                    items:
                        type: string
                    description: Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients).
                card_reveal_enabled:
                    type: boolean
                    description: Whether agents may reveal card details subject to per-card reveal policy.
                card_require_approval:
                    type: boolean
                    default: true
                    description: When true, card orders route through the human approval queue before x402 payment.
                api_key_expires_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: Optional expiration time for the agent's API key.

        UpdateAgentRequest:
            type: object
            properties:
                name:
                    type: string
                scopes:
                    type: array
                    items:
                        type: string
                is_active:
                    type: boolean
                expires_at:
                    type: string
                    format: date-time
                intents_api_enabled:
                    type: boolean
                tx_to_allowlist:
                    type: array
                    items:
                        type: string
                tx_max_value:
                    type: string
                    description: Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX).
                tx_daily_limit:
                    type: string
                    description: Rolling daily spend cap in native major units, enforced per chain family at signing time.
                tx_max_value_eth:
                    type: string
                    deprecated: true
                    description: Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only).
                tx_daily_limit_eth:
                    type: string
                    deprecated: true
                    description: Deprecated alias for tx_daily_limit.
                tx_allowed_chains:
                    type: array
                    items:
                        type: string
                token_ttl_seconds:
                    type: integer
                    nullable: true
                vault_ids:
                    type: array
                    items:
                        type: string
                        format: uuid
                shroud_enabled:
                    type: boolean
                    description: Enable/disable Shroud LLM Proxy
                shroud_config:
                    $ref: "#/components/schemas/ShroudConfig"
                execution_intents_enabled:
                    type: boolean
                    description: Enable/disable Execution Intents for this agent
                execution_guardrails:
                    type: object
                    additionalProperties: true
                    description: Guardrails applied to all execution intents for this agent
                intents_require_tee:
                    type: boolean
                    description: When true, transaction/sign requests must arrive via a TEE host (Pro+ only)
                execution_require_tee:
                    type: boolean
                    description: When true, execute requests must arrive via TEE and all direct secret reads are blocked (Pro+ only)
                tx_max_per_day:
                    type: integer
                    nullable: true
                    description: Max transactions per UTC calendar day. Null = unlimited.
                tx_overhead_budget:
                    type: object
                    nullable: true
                    additionalProperties:
                        type: string
                    description: Per-chain daily overhead budget in native units.
                solana_ata_allowlist:
                    type: array
                    items:
                        type: string
                    description: Solana wallet addresses whose ATAs may be created.
                cards_enabled:
                    type: boolean
                    description: Whether this agent may order payment cards (x402 card ordering). Pro+ tier.
                card_max_order_usd:
                    type: string
                    nullable: true
                    description: Maximum USD amount for a single card order. null clears.
                card_daily_limit_usd:
                    type: string
                    nullable: true
                    description: Maximum cumulative USD spent ordering cards per rolling 24h window. null clears.
                card_payto_allowlist:
                    type: array
                    items:
                        type: string
                    description: Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients).
                card_reveal_enabled:
                    type: boolean
                    description: Whether agents may reveal card details subject to per-card reveal policy.
                card_require_approval:
                    type: boolean
                    description: When true, card orders route through the human approval queue before x402 payment.
                federation_enabled:
                    type: boolean
                    description: |
                        Enable OIDC federation (RFC 8693 token-exchange) for this agent.
                        When true, the agent may call POST /v1/auth/federated-token to mint
                        federation tokens for the audiences listed in `federation_audiences`.
                federation_audiences:
                    type: array
                    items:
                        type: string
                        format: uri
                    description: |
                        Allowlist of `aud` values the federation token-exchange may issue
                        tokens for (e.g. `["https://api.anthropic.com"]`). Empty array
                        blocks all federation requests (zero-trust default).
                federated_token_ttl_seconds:
                    type: integer
                    minimum: 60
                    maximum: 3600
                    nullable: true
                    description: |
                        Per-agent TTL override for federation tokens (seconds). NULL falls
                        back to the global default (`ONECLAW_JWT_FEDERATED_TOKEN_EXPIRY_SECS`).
                        Hard-capped at 3600 seconds.
                tx_token_allowlist:
                    type: array
                    items:
                        type: string
                    description: Token contract/mint addresses this agent may interact with. Empty = unrestricted.
                tx_known_tokens_only:
                    type: boolean
                    default: false
                    description: When true, only tokens in the known_tokens registry may be used.
                xrpl_allowed_tx_types:
                    type: array
                    items:
                        type: string
                    description: Allowed XRP Ledger transaction types (Payment, TrustSet, etc.). Empty = all allowed.
                per_chain_guardrails:
                    type: object
                    additionalProperties: true
                    description: |
                        Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron).
                        Each value may include max_value, daily_limit, to_allowlist, token_allowlist (legacy *_eth keys accepted).
                        Strictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.
                api_key_expires_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: Optional expiration time for the agent's API key. Set to null to clear.

        AgentResponse:
            type: object
            required:
                [
                    id,
                    name,
                    auth_method,
                    is_active,
                    intents_api_enabled,
                    shroud_enabled,
                    created_at,
                ]
            properties:
                id:
                    type: string
                    format: uuid
                name:
                    type: string
                description:
                    type: string
                auth_method:
                    type: string
                    enum: [api_key, mtls, oidc_client_credentials]
                scopes:
                    type: array
                    items:
                        type: string
                is_active:
                    type: boolean
                intents_api_enabled:
                    type: boolean
                tx_to_allowlist:
                    type: array
                    items:
                        type: string
                tx_max_value:
                    type: string
                    description: Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX).
                tx_daily_limit:
                    type: string
                    description: Rolling daily spend cap in native major units, enforced per chain family at signing time.
                tx_max_value_eth:
                    type: string
                    deprecated: true
                    description: Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only).
                tx_daily_limit_eth:
                    type: string
                    deprecated: true
                    description: Deprecated alias for tx_daily_limit.
                tx_spent_today:
                    type: string
                    description: Sum of today's spend across all chain families in major units. Prefer tx_spent_today_by_chain.
                tx_spent_today_eth:
                    type: string
                    deprecated: true
                    description: Deprecated alias for tx_spent_today.
                tx_allowed_chains:
                    type: array
                    items:
                        type: string
                token_ttl_seconds:
                    type: integer
                    nullable: true
                vault_ids:
                    type: array
                    items:
                        type: string
                        format: uuid
                client_cert_fingerprint:
                    type: string
                    description: SHA-256 fingerprint of the client certificate (mTLS agents)
                oidc_issuer:
                    type: string
                    description: OIDC issuer URL (oidc_client_credentials agents)
                oidc_client_id:
                    type: string
                    description: OIDC client ID (oidc_client_credentials agents)
                ssh_public_key:
                    type: string
                    description: Ed25519 SSH public key (base64-encoded, auto-generated at creation)
                ecdh_public_key:
                    type: string
                    description: P-256 ECDH public key (base64 SEC1 uncompressed point, auto-generated at creation)
                shroud_enabled:
                    type: boolean
                    description: Whether this agent routes LLM traffic through the Shroud TEE proxy
                shroud_config:
                    $ref: "#/components/schemas/ShroudConfig"
                execution_intents_enabled:
                    type: boolean
                    description: Whether Execution Intents (bindings and execute endpoint) are enabled for this agent
                execution_guardrails:
                    type: object
                    additionalProperties: true
                    description: Guardrails applied to all execution intents for this agent
                intents_require_tee:
                    type: boolean
                    description: When true, transaction/sign requests must arrive via a TEE host (Pro+ only)
                execution_require_tee:
                    type: boolean
                    description: When true, execute requests must arrive via TEE and all direct secret reads are blocked (Pro+ only)
                tx_max_per_day:
                    type: integer
                    nullable: true
                    description: Max transactions per UTC calendar day. Null = unlimited.
                tx_overhead_budget:
                    type: object
                    nullable: true
                    additionalProperties:
                        type: string
                    description: Per-chain daily overhead budget in native units.
                solana_ata_allowlist:
                    type: array
                    items:
                        type: string
                    description: Solana wallet addresses whose ATAs may be created.
                cards_enabled:
                    type: boolean
                    description: Whether this agent may order payment cards (x402 card ordering).
                card_max_order_usd:
                    type: string
                    description: Maximum USD amount for a single card order.
                card_daily_limit_usd:
                    type: string
                    description: Maximum cumulative USD spent ordering cards per rolling 24h window.
                card_payto_allowlist:
                    type: array
                    items:
                        type: string
                    description: Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients).
                card_reveal_enabled:
                    type: boolean
                    description: Whether agents may reveal card details subject to per-card reveal policy.
                card_require_approval:
                    type: boolean
                    description: When true, card orders route through the human approval queue before x402 payment.
                tx_count_today:
                    type: integer
                    description: Today's transaction count (UTC calendar day). Present when intents_api_enabled.
                tx_overhead_today_by_chain:
                    type: object
                    additionalProperties:
                        type: string
                    description: Today's overhead spend by chain in native units.
                federation_enabled:
                    type: boolean
                    description: |
                        Whether this agent may mint OIDC federation tokens via
                        POST /v1/auth/federated-token. False by default.
                federation_audiences:
                    type: array
                    items:
                        type: string
                        format: uri
                    description: Allowlist of audience URIs the agent may federate to.
                federated_token_ttl_seconds:
                    type: integer
                    nullable: true
                    description: Per-agent TTL override for federation tokens (60..=3600).
                signing_chains:
                    type: array
                    items:
                        type: string
                    description: Chains for which this agent has provisioned signing keys.
                eip712_domain_allowlist:
                    type: array
                    items:
                        type: object
                    description: JSON array of allowed EIP-712 domain entries.
                eip712_default_policy:
                    type: string
                    enum: [deny, allow]
                    description: Default EIP-712 policy (deny blocks all unless allowlisted).
                message_signing_enabled:
                    type: boolean
                    description: Whether EIP-191 personal_sign is enabled.
                raw_signing_enabled:
                    type: boolean
                    description: >
                        Whether the raw/precomputed-digest signing intent (eip712_digest) is
                        enabled. Blind signing — bypasses transaction guardrails; OFF by default
                        and human-set. Required for ERC-1271/ERC-7739 flows (e.g. Polymarket).
                tx_token_allowlist:
                    type: array
                    items:
                        type: string
                    description: Token contract/mint addresses this agent may interact with.
                tx_known_tokens_only:
                    type: boolean
                    description: When true, only tokens in the known_tokens registry may be used.
                xrpl_allowed_tx_types:
                    type: array
                    items:
                        type: string
                    description: Allowed XRP Ledger transaction types.
                per_chain_guardrails:
                    type: object
                    additionalProperties: true
                    description: Per-chain guardrail overrides.
                tx_spent_today_by_chain:
                    type: object
                    additionalProperties:
                        type: string
                    description: 'Per-chain-family daily spend in native major units (keys: evm, bitcoin, solana, xrp, cardano, tron).'
                api_key_expires_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: Optional expiration time for the agent's API key.
                evm_address:
                    type: string
                    nullable: true
                    description: Agent's Ethereum EOA address (used as Safe signer for smart accounts and Intents API).
                created_at:
                    type: string
                    format: date-time
                expires_at:
                    type: string
                    format: date-time
                last_active_at:
                    type: string
                    format: date-time
                smart_accounts:
                    type: array
                    description: Multi-chain; one Safe per chain
                    items:
                        $ref: "#/components/schemas/AgentSmartAccountResponse"

        KnownToken:
            type: object
            required: [id, chain, symbol, name, contract_address, decimals, is_testnet, is_verified]
            properties:
                id:
                    type: string
                    format: uuid
                chain:
                    type: string
                symbol:
                    type: string
                name:
                    type: string
                contract_address:
                    type: string
                decimals:
                    type: integer
                is_testnet:
                    type: boolean
                is_verified:
                    type: boolean
                logo_url:
                    type: string
                    nullable: true
                created_at:
                    type: string
                    format: date-time
                updated_at:
                    type: string
                    format: date-time

        KnownTokenListResponse:
            type: object
            required: [tokens]
            properties:
                tokens:
                    type: array
                    items:
                        $ref: "#/components/schemas/KnownToken"

        CreateKnownTokenRequest:
            type: object
            required: [chain, symbol, name, contract_address, decimals]
            properties:
                chain:
                    type: string
                symbol:
                    type: string
                name:
                    type: string
                contract_address:
                    type: string
                decimals:
                    type: integer
                is_testnet:
                    type: boolean
                    default: false
                is_verified:
                    type: boolean
                    default: true
                logo_url:
                    type: string
                    nullable: true

        AgentSmartAccountResponse:
            type: object
            description: One Safe smart account per chain for an agent
            properties:
                id:
                    type: string
                    format: uuid
                chain:
                    type: string
                chain_id:
                    type: integer
                safe_address:
                    type: string
                nonce:
                    type: string
                init_data:
                    type: object
                created_at:
                    type: string
                    format: date-time

        AddSmartAccountRequest:
            type: object
            required: [chain, chain_id, safe_address]
            properties:
                chain:
                    type: string
                chain_id:
                    type: integer
                safe_address:
                    type: string
                nonce:
                    type: string
                init_data:
                    type: object

        AgentSelfResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                name:
                    type: string
                description:
                    type: string
                org_id:
                    type: string
                    format: uuid
                scopes:
                    type: array
                    items:
                        type: string
                is_active:
                    type: boolean
                intents_api_enabled:
                    type: boolean
                created_by:
                    type: string
                    format: uuid
                created_at:
                    type: string
                    format: date-time
                expires_at:
                    type: string
                    format: date-time
                last_active_at:
                    type: string
                    format: date-time
                ssh_public_key:
                    type: string
                    description: Ed25519 SSH public key (base64-encoded)
                ecdh_public_key:
                    type: string
                    description: P-256 ECDH public key (base64 SEC1 uncompressed point)
                shroud_enabled:
                    type: boolean
                    description: Whether this agent routes LLM traffic through the Shroud TEE proxy
                shroud_config:
                    $ref: "#/components/schemas/ShroudConfig"

        ShroudConfig:
            type: object
            description: Per-agent Shroud LLM Proxy configuration
            properties:
                pii_policy:
                    type: string
                    enum: [block, redact, warn, allow]
                    default: redact
                    description: How PII detections are handled
                injection_threshold:
                    type: number
                    minimum: 0
                    maximum: 1
                    default: 0.7
                    description: Prompt injection score threshold (0.0–1.0). Requests above are blocked
                context_injection_threshold:
                    type: number
                    minimum: 0
                    maximum: 1
                    default: 0.7
                    description: Context injection score threshold (0.0–1.0)
                allowed_providers:
                    type: array
                    items:
                        type: string
                    description: LLM providers this agent may use (empty = all)
                allowed_models:
                    type: array
                    items:
                        type: string
                    description: Specific models allowed (empty = all)
                denied_models:
                    type: array
                    items:
                        type: string
                    description: Models explicitly blocked
                max_tokens_per_request:
                    type: integer
                    description: Maximum input tokens per request
                max_requests_per_minute:
                    type: integer
                    description: Rate limit (requests per minute)
                max_requests_per_day:
                    type: integer
                    description: Rate limit (requests per day)
                daily_budget_usd:
                    type: number
                    description: Daily LLM spend cap in USD (0 = unlimited)
                enable_secret_redaction:
                    type: boolean
                    default: true
                    description: Whether vault secrets are redacted from prompts/responses
                enable_response_filtering:
                    type: boolean
                    default: true
                    description: Whether response credential scanning is active
                unicode_normalization:
                    $ref: "#/components/schemas/UnicodeNormalizationConfig"
                command_injection_detection:
                    $ref: "#/components/schemas/CommandInjectionConfig"
                social_engineering_detection:
                    $ref: "#/components/schemas/SocialEngineeringConfig"
                encoding_detection:
                    $ref: "#/components/schemas/EncodingDetectionConfig"
                network_detection:
                    $ref: "#/components/schemas/NetworkDetectionConfig"
                filesystem_detection:
                    $ref: "#/components/schemas/FilesystemDetectionConfig"
                sanitization_mode:
                    type: string
                    enum: [block, surgical, log_only]
                    default: block
                    description: Global behavior when threats are detected (block=reject, surgical=remove only malicious parts, log_only=audit without action)
                threat_logging:
                    type: boolean
                    default: true
                    description: Whether to log all detected threats to audit (even when action is allow/warn)
                tool_call_inspection:
                    $ref: "#/components/schemas/ToolCallPolicy"
                output_policy:
                    $ref: "#/components/schemas/OutputPolicy"
                secret_injection_detection:
                    $ref: "#/components/schemas/SecretInjectionConfig"
                advanced_redaction:
                    $ref: "#/components/schemas/AdvancedRedactionConfig"
                semantic_policy:
                    $ref: "#/components/schemas/SemanticPolicy"
                flagged_request_retention_days:
                    type: integer
                    minimum: 0
                    maximum: 365
                    description: Number of days to retain flagged request bodies for replay/investigation

        UnicodeNormalizationConfig:
            type: object
            description: Unicode normalization and homoglyph detection settings
            properties:
                enabled:
                    type: boolean
                    default: true
                    description: Enable Unicode normalization
                strip_zero_width:
                    type: boolean
                    default: true
                    description: Remove zero-width and invisible Unicode characters
                normalize_homoglyphs:
                    type: boolean
                    default: true
                    description: Replace look-alike characters (e.g., Cyrillic а → Latin a)
                normalization_form:
                    type: string
                    enum: [NFC, NFKC, NFD, NFKD]
                    default: NFKC
                    description: Unicode normalization form to apply

        CommandInjectionConfig:
            type: object
            description: Shell/command injection detection settings
            properties:
                enabled:
                    type: boolean
                    default: true
                    description: Enable command injection detection
                action:
                    type: string
                    enum: [block, sanitize, warn, log]
                    default: block
                    description: Action when command injection is detected
                patterns:
                    type: string
                    enum: [default, strict, custom]
                    default: default
                    description: Pattern strictness level
                custom_patterns:
                    type: array
                    items:
                        type: string
                    description: Custom regex patterns for detection (only used when patterns=custom)

        SocialEngineeringConfig:
            type: object
            description: Social engineering and manipulation detection settings
            properties:
                enabled:
                    type: boolean
                    default: true
                    description: Enable social engineering detection
                action:
                    type: string
                    enum: [block, warn, log]
                    default: warn
                    description: Action when manipulation attempts are detected
                sensitivity:
                    type: string
                    enum: [low, medium, high]
                    default: medium
                    description: Detection sensitivity level

        EncodingDetectionConfig:
            type: object
            description: Encoding/obfuscation detection settings
            properties:
                enabled:
                    type: boolean
                    default: true
                    description: Enable encoding detection
                action:
                    type: string
                    enum: [block, decode, warn, log]
                    default: warn
                    description: Action when obfuscated content is detected
                detect_base64:
                    type: boolean
                    default: true
                    description: Detect Base64-encoded content
                detect_hex:
                    type: boolean
                    default: true
                    description: Detect hex-encoded content (\\x41, 0x41)
                detect_unicode_escape:
                    type: boolean
                    default: true
                    description: Detect Unicode escape sequences (\\u0041)

        NetworkDetectionConfig:
            type: object
            description: Suspicious URL/domain detection settings
            properties:
                enabled:
                    type: boolean
                    default: true
                    description: Enable network/URL detection
                action:
                    type: string
                    enum: [block, warn, log]
                    default: warn
                    description: Action when suspicious URLs are detected
                blocked_domains:
                    type: array
                    items:
                        type: string
                    description: Domains to always block (e.g., pastebin.com, ngrok.io)
                allowed_domains:
                    type: array
                    items:
                        type: string
                    description: Domains to always allow (allowlist mode when non-empty)

        FilesystemDetectionConfig:
            type: object
            description: Filesystem path detection settings
            properties:
                enabled:
                    type: boolean
                    default: false
                    description: Enable filesystem path detection (disabled by default as it can be noisy)
                action:
                    type: string
                    enum: [block, sanitize, warn, log]
                    default: log
                    description: Action when filesystem paths are detected
                blocked_paths:
                    type: array
                    items:
                        type: string
                    description: Path patterns to block (e.g., /etc/passwd, ~/.ssh)

        ToolCallPolicy:
            type: object
            description: Tool/function call inspection settings
            properties:
                enabled:
                    type: boolean
                    default: false
                    description: Enable tool call inspection
                allowed_tool_names:
                    type: array
                    items:
                        type: string
                    description: Allowed tool/function names (empty = all allowed)
                denied_tool_names:
                    type: array
                    items:
                        type: string
                    description: Denied tool/function names
                scan_arguments:
                    type: boolean
                    default: true
                    description: Scan tool call arguments for credential exfiltration
                block_credential_exfil:
                    type: boolean
                    default: true
                    description: Block tool calls that appear to exfiltrate credentials
                action:
                    type: string
                    enum: [block, sanitize, warn, log]
                    default: block
                    description: Action when a tool call violation is detected

        OutputPolicy:
            type: object
            description: Output content policy settings for LLM responses
            properties:
                enabled:
                    type: boolean
                    default: false
                    description: Enable output content policies
                blocked_patterns:
                    type: array
                    items:
                        type: string
                    description: Custom regex patterns to block in responses
                blocked_entities:
                    type: array
                    items:
                        type: string
                    description: Named entities to block (e.g., competitor names)
                block_harmful_content:
                    type: boolean
                    default: false
                    description: Block responses containing harmful content categories
                harmful_categories:
                    type: array
                    items:
                        type: string
                        enum: [violence, self_harm, illegal, hate, sexual, malware]
                    description: Harm categories to block
                action:
                    type: string
                    enum: [block, sanitize, warn, log]
                    default: warn
                    description: Action when output policy is violated

        SecretInjectionConfig:
            type: object
            description: Detects credentials injected into prompts that are not from the vault
            properties:
                enabled:
                    type: boolean
                    default: false
                    description: Enable secret injection detection
                action:
                    type: string
                    enum: [block, sanitize, warn, log]
                    default: block
                    description: Action when injected credentials are detected
                sensitivity:
                    type: string
                    enum: [low, medium, high]
                    default: medium
                    description: Detection sensitivity level

        AdvancedRedactionConfig:
            type: object
            description: Advanced secret redaction settings (base64-encoded, split, prefix leaks)
            properties:
                enabled:
                    type: boolean
                    default: false
                    description: Enable advanced redaction checks
                detect_base64_encoded:
                    type: boolean
                    default: false
                    description: Detect base64-encoded vault secrets
                detect_split_secrets:
                    type: boolean
                    default: false
                    description: Detect secrets split across tokens or messages
                detect_prefix_leak:
                    type: boolean
                    default: false
                    description: Detect partial/prefix leaks of vault secrets
                min_secret_length:
                    type: integer
                    default: 16
                    description: Minimum secret length to consider for advanced matching

        SemanticPolicy:
            type: object
            description: Semantic/intent-level policy enforcement
            properties:
                enabled:
                    type: boolean
                    default: false
                    description: Enable semantic policy enforcement
                allowed_topics:
                    type: array
                    items:
                        type: string
                    description: Topics the agent is allowed to discuss (empty = all)
                denied_topics:
                    type: array
                    items:
                        type: string
                    description: Topics to block
                allowed_tasks:
                    type: array
                    items:
                        type: string
                    description: Tasks the agent is allowed to perform (empty = all)
                denied_tasks:
                    type: array
                    items:
                        type: string
                    description: Tasks to block (e.g., code_generation, data_export)
                action:
                    type: string
                    enum: [block, sanitize, warn, log]
                    default: warn
                    description: Action when semantic policy is violated

        AgentCreatedResponse:
            type: object
            required: [agent]
            properties:
                agent:
                    $ref: "#/components/schemas/AgentResponse"
                api_key:
                    type: string
                    description: One-time API key (only present for api_key auth method)

        AgentListResponse:
            type: object
            properties:
                agents:
                    type: array
                    items:
                        $ref: "#/components/schemas/AgentResponse"

        AgentKeyRotatedResponse:
            type: object
            properties:
                api_key:
                    type: string

        # --- Transactions ---

        SubmitTransactionRequest:
            type: object
            required: [to, value, chain]
            properties:
                to:
                    type: string
                    description: Destination address (0x-prefixed)
                value:
                    type: string
                    description: Value in ETH
                chain:
                    type: string
                    description: Chain name or numeric ID
                data:
                    type: string
                    description: Hex-encoded calldata
                signing_key_path:
                    type: string
                    description: Vault path to signing key. Auto-resolves per-chain signing key if provisioned, otherwise keys/{chain}-signer.
                nonce:
                    type: integer
                gas_price:
                    type: string
                gas_limit:
                    type: integer
                max_fee_per_gas:
                    type: string
                max_priority_fee_per_gas:
                    type: string
                simulate_first:
                    type: boolean
                    default: false
                mode:
                    type: string
                    description: Transaction mode
                    enum: [eoa, smart_account]
                    default: eoa
                gasless:
                    type: boolean
                    description: Whether to submit as a gasless (sponsored) transaction
                    default: false
                destination_tag:
                    type: integer
                    description: "Non-EVM (XRP): destination tag for exchange deposits"
                memo:
                    type: string
                    description: "Non-EVM (XRP, Solana): optional memo"
                fee_rate_sat_per_vbyte:
                    type: integer
                    description: "Non-EVM (Bitcoin): override the fetched fee rate (sat/vByte)"
                fee_limit_sun:
                    type: integer
                    description: "Non-EVM (Tron): TRC-20 energy fee limit in sun"
                token_mint:
                    type: string
                    description: "Non-EVM (Solana SPL / Tron TRC-20): token mint or contract address; omit for native transfer"
                token_decimals:
                    type: integer
                    description: "Non-EVM (Solana, Tron): token decimals (default 6)"
                ttl:
                    type: integer
                    description: "Non-EVM (Cardano): transaction time-to-live (absolute slot)"
                xrpl_tx_json:
                    type: object
                    additionalProperties: true
                    description: >
                        Raw XRPL transaction JSON for full transaction type coverage.
                        When present (and chain is XRP), the handler uses the xrpl-rust
                        binary codec to encode and sign the transaction as-is. Supports
                        all XRPL transaction types: Payment, TrustSet, OfferCreate,
                        OfferCancel, AccountSet, EscrowCreate, NFTokenMint, AMMCreate,
                        and 20+ more. Account, Sequence, Fee, LastLedgerSequence, and
                        SigningPubKey are auto-filled when absent.

        SignTransactionRequest:
            type: object
            required: [to, value, chain]
            properties:
                to:
                    type: string
                    description: Destination address (0x-prefixed)
                value:
                    type: string
                    description: Value in ETH
                chain:
                    type: string
                    description: Chain name or numeric ID
                data:
                    type: string
                    description: Hex-encoded calldata
                signing_key_path:
                    type: string
                    description: Vault path to signing key. Auto-resolves per-chain signing key if provisioned, otherwise keys/{chain}-signer.
                nonce:
                    type: integer
                gas_price:
                    type: string
                gas_limit:
                    type: integer
                max_fee_per_gas:
                    type: string
                max_priority_fee_per_gas:
                    type: string
                simulate_first:
                    type: boolean
                    default: false
                destination_tag:
                    type: integer
                    description: "Non-EVM (XRP): destination tag for exchange deposits"
                memo:
                    type: string
                    description: "Non-EVM (XRP, Solana): optional memo"
                fee_rate_sat_per_vbyte:
                    type: integer
                    description: "Non-EVM (Bitcoin): override the fetched fee rate (sat/vByte)"
                fee_limit_sun:
                    type: integer
                    description: "Non-EVM (Tron): TRC-20 energy fee limit in sun"
                token_mint:
                    type: string
                    description: "Non-EVM (Solana SPL / Tron TRC-20): token mint or contract address; omit for native transfer"
                token_decimals:
                    type: integer
                    description: "Non-EVM (Solana, Tron): token decimals (default 6)"
                ttl:
                    type: integer
                    description: "Non-EVM (Cardano): transaction time-to-live (absolute slot)"
                xrpl_tx_json:
                    type: object
                    additionalProperties: true
                    description: >
                        Raw XRPL transaction JSON for full transaction type coverage.
                        When present (and chain is XRP), the handler uses the xrpl-rust
                        binary codec to encode and sign the transaction as-is. Supports
                        all XRPL transaction types: Payment, TrustSet, OfferCreate,
                        OfferCancel, AccountSet, EscrowCreate, NFTokenMint, AMMCreate,
                        and 20+ more. Account, Sequence, Fee, LastLedgerSequence, and
                        SigningPubKey are auto-filled when absent.

        SignTransactionResponse:
            type: object
            properties:
                signed_tx:
                    type: string
                    description: Raw signed transaction hex (always included)
                tx_hash:
                    type: string
                from:
                    type: string
                    description: Derived sender address
                to:
                    type: string
                chain:
                    type: string
                chain_id:
                    type: integer
                nonce:
                    type: integer
                value_wei:
                    type: string
                status:
                    type: string
                    enum: [sign_only]
                simulation_id:
                    type: string
                simulation_status:
                    type: string
                max_fee_per_gas:
                    type: string
                max_priority_fee_per_gas:
                    type: string

        SimulateTransactionRequest:
            type: object
            required: [to, value, chain]
            properties:
                to:
                    type: string
                value:
                    type: string
                chain:
                    type: string
                data:
                    type: string
                signing_key_path:
                    type: string
                    description: Vault path to signing key. Auto-resolves per-chain signing key if provisioned, otherwise keys/{chain}-signer.
                gas_limit:
                    type: integer

        SimulateBundleRequest:
            type: object
            required: [transactions]
            properties:
                transactions:
                    type: array
                    items:
                        $ref: "#/components/schemas/SimulateTransactionRequest"

        # Signing Keys (Multi-Chain)
        CreateSigningKeyRequest:
            type: object
            required: [chain]
            properties:
                chain:
                    type: string
                    enum: [ethereum, bitcoin, solana, xrp, cardano, tron]

        SigningKeyResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                agent_id:
                    type: string
                    format: uuid
                chain:
                    type: string
                curve:
                    type: string
                public_key:
                    type: string
                address:
                    type: string
                    nullable: true
                key_version:
                    type: integer
                is_active:
                    type: boolean
                created_at:
                    type: string
                    format: date-time
                rotated_at:
                    type: string
                    format: date-time
                    nullable: true

        SigningKeyListResponse:
            type: object
            properties:
                keys:
                    type: array
                    items:
                        $ref: "#/components/schemas/SigningKeyResponse"

        # Bankr Dynamic Key Vending
        LeaseBankrKeyRequest:
            type: object
            properties:
                wallet_id:
                    type: string
                    description: Bankr wallet ID (wlt_...). Uses org default if omitted.
                ttl_seconds:
                    type: integer
                    description: Lease TTL in seconds (default 3600, max 86400).
                    minimum: 60
                    maximum: 86400
                permissions:
                    $ref: "#/components/schemas/LeaseBankrPermissions"

        LeaseBankrPermissions:
            type: object
            properties:
                llm_gateway_enabled:
                    type: boolean
                    default: true
                agent_api_enabled:
                    type: boolean
                    default: false
                read_only:
                    type: boolean
                    default: true

        LeaseBankrKeyResponse:
            type: object
            properties:
                lease_id:
                    type: string
                    format: uuid
                api_key:
                    type: string
                    description: Ephemeral bk_usr_ key. Present for human callers only; omitted for agent JWTs.
                wallet_id:
                    type: string
                expires_at:
                    type: string
                    format: date-time

        BankrKeyLeaseResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                wallet_id:
                    type: string
                bankr_key_id:
                    type: string
                permissions:
                    type: object
                expires_at:
                    type: string
                    format: date-time
                created_at:
                    type: string
                    format: date-time

        BankrKeyLeaseListResponse:
            type: object
            properties:
                leases:
                    type: array
                    items:
                        $ref: "#/components/schemas/BankrKeyLeaseResponse"

        # Unified Signing Intent
        SignIntentRequest:
            type: object
            required: [intent_type, chain]
            properties:
                intent_type:
                    type: string
                    enum: [personal_sign, typed_data, eip712_digest, transaction]
                chain:
                    type: string
                signing_key_path:
                    type: string
                    description: Vault path to signing key. Auto-resolves per-chain signing key if provisioned, otherwise keys/{chain}-signer.
                message:
                    type: string
                    description: Hex-encoded message bytes (for personal_sign)
                typed_data:
                    type: object
                    description: EIP-712 typed data JSON (for typed_data)
                hash:
                    type: string
                    description: >
                        Client-computed 32-byte digest (0x-prefixed) for the eip712_digest
                        intent. Signed directly (blind signing); requires the agent's
                        raw_signing_enabled flag. Use for ERC-1271/ERC-7739 nested EIP-712
                        flows (e.g. Polymarket) where the canonical hash is computed client-side.
                tx_type:
                    type: integer
                    description: "EIP-2718 type: 0=legacy, 1=2930, 2=1559, 3=4844, 4=7702"
                to:
                    type: string
                value:
                    type: string
                data:
                    type: string
                nonce:
                    type: integer
                gas_limit:
                    type: integer
                gas_price:
                    type: string
                max_fee_per_gas:
                    type: string
                max_priority_fee_per_gas:
                    type: string
                access_list:
                    type: array
                    items:
                        type: object
                max_fee_per_blob_gas:
                    type: string
                blob_versioned_hashes:
                    type: array
                    items:
                        type: string
                authorization_list:
                    type: array
                    items:
                        type: object
                sign_only:
                    type: boolean
                    description: "When true, sign only (do not broadcast). Non-EVM transaction intents only."
                destination_tag:
                    type: integer
                    description: "Non-EVM (XRP): destination tag for exchange deposits"
                memo:
                    type: string
                    description: "Non-EVM (XRP, Solana): optional memo"
                fee_rate_sat_per_vbyte:
                    type: integer
                    description: "Non-EVM (Bitcoin): override the fetched fee rate (sat/vByte)"
                fee_limit_sun:
                    type: integer
                    description: "Non-EVM (Tron): TRC-20 energy fee limit in sun"
                token_mint:
                    type: string
                    description: "Non-EVM (Solana SPL / Tron TRC-20): token mint or contract address; omit for native transfer"
                token_decimals:
                    type: integer
                    description: "Non-EVM (Solana, Tron): token decimals (default 6)"
                ttl:
                    type: integer
                    description: "Non-EVM (Cardano): transaction time-to-live (absolute slot)"
                xrpl_tx_json:
                    type: object
                    additionalProperties: true
                    description: >
                        Raw XRPL transaction JSON for full transaction type coverage.
                        When present (and chain is XRP), the handler uses the xrpl-rust
                        binary codec to encode and sign the transaction as-is. Supports
                        all XRPL transaction types: Payment, TrustSet, OfferCreate,
                        OfferCancel, AccountSet, EscrowCreate, NFTokenMint, AMMCreate,
                        and 20+ more. Account, Sequence, Fee, LastLedgerSequence, and
                        SigningPubKey are auto-filled when absent.

        SignIntentResponse:
            type: object
            properties:
                intent_type:
                    type: string
                chain:
                    type: string
                from:
                    type: string
                signature:
                    type: string
                    nullable: true
                signed_tx:
                    type: string
                    nullable: true
                tx_hash:
                    type: string
                    nullable: true
                message_hash:
                    type: string
                    nullable: true
                typed_data_hash:
                    type: string
                    nullable: true
                tx_type:
                    type: integer
                    nullable: true

        TransactionResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                agent_id:
                    type: string
                    format: uuid
                chain:
                    type: string
                chain_id:
                    type: integer
                to:
                    type: string
                value_wei:
                    type: string
                status:
                    type: string
                    enum:
                        [pending, signed, sign_only, broadcast, failed, simulation_failed]
                signed_tx:
                    type: string
                    nullable: true
                    description: >
                        Raw signed transaction hex. On GET list and GET by id, this property is omitted by default (absent from the response). Pass `include_signed_tx=true` on those endpoints to include it. Always present on the initial POST submit response.
                tx_hash:
                    type: string
                error_message:
                    type: string
                created_at:
                    type: string
                    format: date-time
                signed_at:
                    type: string
                    format: date-time
                simulation_id:
                    type: string
                simulation_status:
                    type: string
                tenderly_dashboard_url:
                    type: string
                    format: uri
                max_fee_per_gas:
                    type: string
                max_priority_fee_per_gas:
                    type: string

        TransactionListResponse:
            type: object
            properties:
                transactions:
                    type: array
                    items:
                        $ref: "#/components/schemas/TransactionResponse"

        BalanceChange:
            type: object
            properties:
                address:
                    type: string
                token:
                    type: string
                token_symbol:
                    type: string
                before:
                    type: string
                after:
                    type: string
                change:
                    type: string

        SimulationResponse:
            type: object
            properties:
                simulation_id:
                    type: string
                status:
                    type: string
                    enum: [success, reverted, error]
                gas_used:
                    type: integer
                gas_estimate_usd:
                    type: string
                balance_changes:
                    type: array
                    items:
                        $ref: "#/components/schemas/BalanceChange"
                error:
                    type: string
                error_code:
                    type: string
                error_human_readable:
                    type: string
                revert_reason:
                    type: string
                tenderly_dashboard_url:
                    type: string
                    format: uri
                simulated_at:
                    type: string
                    format: date-time

        BundleSimulationResponse:
            type: object
            properties:
                simulations:
                    type: array
                    items:
                        $ref: "#/components/schemas/SimulationResponse"

        # --- Chains ---

        ChainResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                name:
                    type: string
                display_name:
                    type: string
                chain_id:
                    type: integer
                rpc_url:
                    type: string
                ws_url:
                    type: string
                explorer_url:
                    type: string
                native_currency:
                    type: string
                is_testnet:
                    type: boolean
                is_enabled:
                    type: boolean
                created_at:
                    type: string
                    format: date-time
                updated_at:
                    type: string
                    format: date-time

        ChainListResponse:
            type: object
            properties:
                chains:
                    type: array
                    items:
                        $ref: "#/components/schemas/ChainResponse"

        CreateChainRequest:
            type: object
            required: [name, display_name, chain_id]
            properties:
                name:
                    type: string
                display_name:
                    type: string
                chain_id:
                    type: integer
                rpc_url:
                    type: string
                ws_url:
                    type: string
                explorer_url:
                    type: string
                native_currency:
                    type: string
                    default: ETH
                is_testnet:
                    type: boolean
                    default: false
                is_enabled:
                    type: boolean
                    default: true

        UpdateChainRequest:
            type: object
            properties:
                display_name:
                    type: string
                rpc_url:
                    type: string
                ws_url:
                    type: string
                explorer_url:
                    type: string
                native_currency:
                    type: string
                is_testnet:
                    type: boolean
                is_enabled:
                    type: boolean

        # --- Sharing ---

        CreateShareRequest:
            type: object
            required: [recipient_type, expires_at]
            properties:
                recipient_type:
                    type: string
                    enum:
                        [user, agent, external_email, anyone_with_link, creator]
                recipient_id:
                    type: string
                    format: uuid
                email:
                    type: string
                    format: email
                permissions:
                    type: array
                    items:
                        type: string
                max_access_count:
                    type: integer
                expires_at:
                    type: string
                    format: date-time
                passphrase:
                    type: string
                ip_allowlist:
                    type: array
                    items:
                        type: string

        ShareResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                share_url:
                    type: string
                    format: uri
                recipient_type:
                    type: string
                recipient_email:
                    type: string
                expires_at:
                    type: string
                    format: date-time
                max_access_count:
                    type: integer

        SharedSecretResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                path:
                    type: string
                type:
                    type: string
                value:
                    type: string
                access_count:
                    type: integer
                max_access_count:
                    type: integer

        ShareListItem:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                secret_path:
                    type: string
                recipient_type:
                    type: string
                recipient_email:
                    type: string
                access_count:
                    type: integer
                max_access_count:
                    type: integer
                expires_at:
                    type: string
                    format: date-time
                created_at:
                    type: string
                    format: date-time
                is_expired:
                    type: boolean
                is_accepted:
                    type: boolean

        ShareListResponse:
            type: object
            properties:
                shares:
                    type: array
                    items:
                        $ref: "#/components/schemas/ShareListItem"

        # --- Organization ---

        OrgMemberResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                email:
                    type: string
                display_name:
                    type: string
                role:
                    type: string
                auth_method:
                    type: string
                created_at:
                    type: string
                    format: date-time

        OrgMemberListResponse:
            type: object
            properties:
                members:
                    type: array
                    items:
                        $ref: "#/components/schemas/OrgMemberResponse"

        UpdateMemberRoleRequest:
            type: object
            required: [role]
            properties:
                role:
                    type: string
                    enum: [owner, admin, member]

        InviteMemberRequest:
            type: object
            required: [email]
            properties:
                email:
                    type: string
                    format: email
                role:
                    type: string

        InviteMemberResponse:
            type: object
            properties:
                message:
                    type: string
                email:
                    type: string

        AgentKeysVaultResponse:
            type: object
            properties:
                vault_id:
                    type: string
                    format: uuid

        OrgBankrConfigResponse:
            type: object
            properties:
                configured:
                    type: boolean
                partner_key_prefix:
                    type: string
                default_wallet_id:
                    type: string
                updated_at:
                    type: string
                    format: date-time
                using_platform_fallback:
                    type: boolean

        UpsertOrgBankrConfigRequest:
            type: object
            required: [partner_key]
            properties:
                partner_key:
                    type: string
                    description: Bankr partner API key (bk_ptr_...)
                default_wallet_id:
                    type: string
                    description: Default provisioned wallet (wlt_...)

        # --- Billing ---

        UsageSummaryResponse:
            type: object
            properties:
                billing_tier:
                    type: string
                free_tier_limit:
                    type: integer
                current_month:
                    type: object
                    properties:
                        total_requests:
                            type: integer
                        paid_requests:
                            type: integer
                        free_requests:
                            type: integer
                        total_cost_usd:
                            type: string

        UsageHistoryResponse:
            type: object
            properties:
                events:
                    type: array
                    items:
                        type: object
                        properties:
                            id:
                                type: string
                                format: uuid
                            principal_type:
                                type: string
                            principal_id:
                                type: string
                            method:
                                type: string
                            endpoint:
                                type: string
                            status_code:
                                type: integer
                            price_usd:
                                type: string
                            is_paid:
                                type: boolean
                            created_at:
                                type: string
                                format: date-time

        SubscribeRequest:
            type: object
            required: [tier, interval]
            properties:
                tier:
                    type: string
                    enum: [pro, business]
                interval:
                    type: string
                    enum: [monthly, yearly]
                trial:
                    type: boolean
                    default: true

        TopupRequest:
            type: object
            required: [amount_usd]
            properties:
                amount_usd:
                    type: integer
                    minimum: 5
                    maximum: 1000

        OverageMethodRequest:
            type: object
            required: [method]
            properties:
                method:
                    type: string
                    enum: [credits, x402]

        CheckoutUrlResponse:
            type: object
            properties:
                checkout_url:
                    type: string
                    format: uri

        PortalUrlResponse:
            type: object
            properties:
                portal_url:
                    type: string
                    format: uri

        SubscriptionResponse:
            type: object
            properties:
                tier:
                    type: string
                interval:
                    type: string
                period_end:
                    type: string
                    format: date-time
                status:
                    type: string
                credit_balance_cents:
                    type: integer
                credit_balance_usd:
                    type: string
                overage_method:
                    type: string
                usage:
                    type: object
                    properties:
                        requests:
                            $ref: "#/components/schemas/UsageMeter"
                        secrets:
                            $ref: "#/components/schemas/UsageMeter"
                        agents:
                            $ref: "#/components/schemas/UsageMeter"
                        vaults:
                            $ref: "#/components/schemas/UsageMeter"
                        team_members:
                            $ref: "#/components/schemas/UsageMeter"
                        intent_transactions:
                            $ref: "#/components/schemas/UsageMeter"
                        shares:
                            $ref: "#/components/schemas/UsageMeter"

        UsageMeter:
            type: object
            properties:
                used:
                    type: integer
                limit:
                    type: integer

        LlmMeteredInvoiceLine:
            type: object
            description: Metered line from Stripe upcoming invoice (usage detail when available).
            properties:
                description:
                    type: string
                    nullable: true
                amount_cents:
                    type: integer
                    format: int64
                quantity:
                    type: number
                    nullable: true
                    description: Billed usage units when Stripe returns quantity (e.g. tokens).
                price_nickname:
                    type: string
                    nullable: true

        LlmBillingCycleUsage:
            type: object
            description: Accrued LLM charges for the current Stripe subscription period (upcoming invoice).
            properties:
                period_start:
                    type: string
                    format: date-time
                    nullable: true
                period_end:
                    type: string
                    format: date-time
                    nullable: true
                accrued_usage_cents:
                    type: integer
                    format: int64
                currency:
                    type: string
                metered_lines:
                    type: array
                    items:
                        $ref: "#/components/schemas/LlmMeteredInvoiceLine"

        LlmCreditBalance:
            type: object
            properties:
                available_cents:
                    type: integer
                    format: int64
                ledger_cents:
                    type: integer
                    format: int64
                used_cents:
                    type: integer
                    format: int64
                currency:
                    type: string

        LlmTokenBillingStatus:
            type: object
            required: [enabled]
            properties:
                enabled:
                    type: boolean
                subscription_status:
                    type: string
                    enum: [active, inactive]
                credit_balance:
                    $ref: "#/components/schemas/LlmCreditBalance"
                billing_cycle_usage:
                    $ref: "#/components/schemas/LlmBillingCycleUsage"

        LlmCheckoutResponse:
            type: object
            properties:
                checkout_url:
                    type: string
                    format: uri

        LlmDisableResponse:
            type: object
            properties:
                enabled:
                    type: boolean

        CreditBalanceResponse:
            type: object
            properties:
                balance_cents:
                    type: integer
                balance_usd:
                    type: string
                expiring_within_90_days:
                    type: object
                    properties:
                        amount_cents:
                            type: integer
                        earliest_expiry:
                            type: string
                            format: date-time

        CreditTransactionsListResponse:
            type: object
            properties:
                transactions:
                    type: array
                    items:
                        type: object
                        properties:
                            id:
                                type: string
                                format: uuid
                            type:
                                type: string
                            amount_cents:
                                type: integer
                            balance_after_cents:
                                type: integer
                            description:
                                type: string
                            created_at:
                                type: string
                                format: date-time
                page:
                    type: integer
                limit:
                    type: integer

        OverageMethodResponse:
            type: object
            properties:
                overage_method:
                    type: string

        # --- Audit ---

        AuditEventsResponse:
            type: object
            properties:
                events:
                    type: array
                    items:
                        $ref: "#/components/schemas/AuditEvent"
                count:
                    type: integer

        AuditEvent:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                action:
                    type: string
                actor_id:
                    type: string
                actor_type:
                    type: string
                resource_type:
                    type: string
                resource_id:
                    type: string
                org_id:
                    type: string
                    format: uuid
                details:
                    type: object
                    additionalProperties: true
                ip_address:
                    type: string
                created_at:
                    type: string
                    format: date-time

        # --- Security ---

        CreateIpRuleRequest:
            type: object
            required: [rule_type, cidr]
            properties:
                rule_type:
                    type: string
                    enum: [allow, deny]
                cidr:
                    type: string
                label:
                    type: string
                applies_to:
                    type: string

        IpRuleResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                org_id:
                    type: string
                    format: uuid
                rule_type:
                    type: string
                cidr:
                    type: string
                label:
                    type: string
                applies_to:
                    type: string
                created_by:
                    type: string
                created_at:
                    type: string
                    format: date-time

        IpRulesListResponse:
            type: object
            properties:
                rules:
                    type: array
                    items:
                        $ref: "#/components/schemas/IpRuleResponse"

        # --- Admin ---

        SettingResponse:
            type: object
            properties:
                key:
                    type: string
                value:
                    type: string
                updated_by:
                    type: string
                updated_at:
                    type: string
                    format: date-time

        SettingsListResponse:
            type: object
            properties:
                settings:
                    type: array
                    items:
                        $ref: "#/components/schemas/SettingResponse"

        UpdateSettingRequest:
            type: object
            required: [value]
            properties:
                value:
                    type: string

        X402ConfigResponse:
            type: object
            properties:
                pay_to:
                    type: string
                network:
                    type: string
                scheme:
                    type: string
                free_tier_limit:
                    type: integer
                facilitator_url:
                    type: string

        AdminUsersListResponse:
            type: object
            properties:
                users:
                    type: array
                    items:
                        type: object
                        properties:
                            id:
                                type: string
                                format: uuid
                            email:
                                type: string
                            display_name:
                                type: string
                            role:
                                type: string
                            auth_method:
                                type: string
                            org_id:
                                type: string
                                format: uuid
                            org_name:
                                type: string
                            billing_tier:
                                type: string
                            created_at:
                                type: string
                                format: date-time
                            free_tier_override:
                                type: integer
                            is_sponsored:
                                type: boolean
                            current_month_requests:
                                type: integer
                total:
                    type: integer

        UpdateOrgLimitsRequest:
            type: object
            properties:
                free_tier_override:
                    type: integer
                is_sponsored:
                    type: boolean

        OrgLimitsResponse:
            type: object
            properties:
                org_id:
                    type: string
                    format: uuid
                free_tier_override:
                    type: integer
                is_sponsored:
                    type: boolean

        SetBillingTierRequest:
            type: object
            required: [tier]
            properties:
                tier:
                    type: string
                    enum: [free, pro, business, enterprise]
                duration_days:
                    type: integer
                    description: How many days the tier lasts (default 365). Use 90 for a 3-month trial.
                    minimum: 1
                    maximum: 3650

        # --- Treasury ---

        CreateTreasuryRequest:
            type: object
            required: [name, safe_address]
            properties:
                name:
                    type: string
                    description: Display name (1–128 characters)
                safe_address:
                    type: string
                    description: Deployed Safe contract address (0x-prefixed, 42 characters)
                chain:
                    type: string
                    description: Chain name (default base)
                chain_id:
                    type: integer
                    description: EVM chain ID (default 8453 for Base)
                threshold:
                    type: integer
                    minimum: 1
                    description: Safe threshold (default 1)
                signers:
                    type: array
                    items:
                        $ref: "#/components/schemas/CreateTreasurySignerEntry"

        CreateTreasurySignerEntry:
            type: object
            required: [signer_type, signer_id, signer_address]
            properties:
                signer_type:
                    type: string
                    enum: [user, agent]
                signer_id:
                    type: string
                    format: uuid
                signer_address:
                    type: string
                    description: EVM address (0x-prefixed)

        UpdateTreasuryRequest:
            type: object
            properties:
                name:
                    type: string
                threshold:
                    type: integer
                    minimum: 1

        TreasuryResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                name:
                    type: string
                safe_address:
                    type: string
                chain:
                    type: string
                chain_id:
                    type: integer
                threshold:
                    type: integer
                created_by:
                    type: string
                    format: uuid
                signers:
                    type: array
                    items:
                        $ref: "#/components/schemas/TreasurySignerResponse"
                created_at:
                    type: string
                    format: date-time

        TreasurySignerResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                signer_type:
                    type: string
                    enum: [user, agent]
                signer_id:
                    type: string
                    format: uuid
                signer_address:
                    type: string
                added_at:
                    type: string
                    format: date-time

        AddSignerRequest:
            type: object
            required: [signer_type, signer_id, signer_address]
            properties:
                signer_type:
                    type: string
                    enum: [user, agent]
                signer_id:
                    type: string
                    format: uuid
                signer_address:
                    type: string

        AccessRequestResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                treasury_id:
                    type: string
                    format: uuid
                agent_id:
                    type: string
                    format: uuid
                status:
                    type: string
                    enum: [pending, approved, denied]
                reason:
                    type: string
                requested_at:
                    type: string
                    format: date-time
                resolved_by:
                    type: string
                    format: uuid
                resolved_at:
                    type: string
                    format: date-time

        # --- Treasury Proposals ---

        CreateTreasuryProposalRequest:
            type: object
            required: [to_address, value_wei, chain]
            properties:
                to_address:
                    type: string
                    description: Destination address (0x-prefixed)
                value_wei:
                    type: string
                    description: Transaction value in wei
                chain:
                    type: string
                    description: Chain name (e.g. ethereum, base)
                chain_id:
                    type: integer
                    description: Numeric chain ID (alternative to chain name)
                data_hex:
                    type: string
                    description: Hex-encoded calldata (optional)
                operation:
                    type: integer
                    description: Safe operation type (0 = Call, 1 = DelegateCall)
                    default: 0

        SignTreasuryProposalRequest:
            type: object
            required: [decision]
            properties:
                decision:
                    type: string
                    enum: [approve, reject]
                    description: Whether to approve or reject the proposal
                signature:
                    type: string
                    description: EIP-712 signature (hex). If omitted, server signs with caller's key.

        TreasuryProposalResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                treasury_id:
                    type: string
                    format: uuid
                proposed_by:
                    type: string
                    format: uuid
                proposed_by_type:
                    type: string
                    enum: [user, agent]
                chain:
                    type: string
                chain_id:
                    type: integer
                safe_address:
                    type: string
                to_address:
                    type: string
                value_wei:
                    type: string
                data_hex:
                    type: string
                    nullable: true
                operation:
                    type: integer
                safe_tx_hash:
                    type: string
                    nullable: true
                nonce:
                    type: integer
                    nullable: true
                status:
                    type: string
                    enum: [pending, approved, executing, executed, rejected, expired]
                threshold:
                    type: integer
                expires_at:
                    type: string
                    format: date-time
                    nullable: true
                executed_tx_hash:
                    type: string
                    nullable: true
                executed_at:
                    type: string
                    format: date-time
                    nullable: true
                signatures:
                    type: array
                    items:
                        $ref: "#/components/schemas/ProposalSignatureResponse"
                created_at:
                    type: string
                    format: date-time

        ProposalSignatureResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                signer_id:
                    type: string
                    format: uuid
                signer_type:
                    type: string
                    enum: [user, agent]
                signer_address:
                    type: string
                signature:
                    type: string
                decision:
                    type: string
                    enum: [approve, reject]
                created_at:
                    type: string
                    format: date-time

        TreasuryProposalListResponse:
            type: object
            properties:
                proposals:
                    type: array
                    items:
                        $ref: "#/components/schemas/TreasuryProposalResponse"

        # --- Treasury Wallets ---

        GenerateTreasuryWalletsRequest:
            type: object
            properties:
                chains:
                    type: array
                    items:
                        type: string
                    description: "Chains to generate wallets for (e.g. [\"ethereum\", \"solana\"]). Omit for all supported chains."

        TreasuryWalletResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                chain:
                    type: string
                curve:
                    type: string
                    description: "Cryptographic curve (e.g. secp256k1, ed25519)"
                public_key_hex:
                    type: string
                address:
                    type: string
                is_active:
                    type: boolean
                created_at:
                    type: string
                    format: date-time

        TreasuryWalletListResponse:
            type: object
            properties:
                wallets:
                    type: array
                    items:
                        $ref: "#/components/schemas/TreasuryWalletResponse"

        TreasuryWalletExportResponse:
            type: object
            properties:
                chain:
                    type: string
                address:
                    type: string
                private_key_hex:
                    type: string
                    description: Raw private key in hex encoding. Handle with extreme care.

        TreasuryWalletBalanceResponse:
            type: object
            required: [chain, address, native]
            properties:
                chain:
                    type: string
                address:
                    type: string
                native:
                    type: object
                    required: [symbol, balance_wei, balance_display]
                    properties:
                        symbol:
                            type: string
                        balance_wei:
                            type: string
                        balance_display:
                            type: string
                tokens:
                    type: array
                    items:
                        type: object
                        required: [contract_address, balance_raw]
                        properties:
                            contract_address:
                                type: string
                            balance_raw:
                                type: string

        TreasuryWalletSendRequest:
            type: object
            required: [to, value_wei]
            properties:
                to:
                    type: string
                    description: Destination address (0x-prefixed)
                value_wei:
                    type: string
                    description: Value in wei
                data:
                    type: string
                    description: Hex-encoded calldata (optional)
                gas_limit:
                    type: integer
                    description: Gas limit override
                gasless:
                    type: boolean
                    description: When true, submits as a gasless (ERC-4337) transaction via Pimlico paymaster. The paymaster sponsors the gas cost.
                    default: false

        TreasuryWalletSendResponse:
            type: object
            required: [tx_hash, from, to, value_wei, chain, status]
            properties:
                tx_hash:
                    type: string
                from:
                    type: string
                to:
                    type: string
                value_wei:
                    type: string
                chain:
                    type: string
                status:
                    type: string
                user_op_hash:
                    type: string
                    description: UserOperation hash (only present for gasless sends via paymaster)

        TreasuryWalletSwapRequest:
            type: object
            required: [sell_token, buy_token, sell_amount]
            properties:
                sell_token:
                    type: string
                    description: Address of the token to sell (or "native" for ETH)
                buy_token:
                    type: string
                    description: Address of the token to buy (or "native" for ETH)
                sell_amount:
                    type: string
                    description: Amount to sell in token's smallest unit

        TreasuryWalletSwapResponse:
            type: object
            required: [tx_hash, sell_token, buy_token, sell_amount, buy_amount, chain, status]
            properties:
                tx_hash:
                    type: string
                sell_token:
                    type: string
                buy_token:
                    type: string
                sell_amount:
                    type: string
                buy_amount:
                    type: string
                chain:
                    type: string
                status:
                    type: string

        # --- Webhooks ---

        CreateWebhookRequest:
            type: object
            required: [url, events]
            properties:
                url:
                    type: string
                    format: uri
                    description: HTTPS URL to deliver webhook events to
                events:
                    type: array
                    items:
                        type: string
                    description: Event types to subscribe to
                description:
                    type: string

        UpdateWebhookRequest:
            type: object
            properties:
                url:
                    type: string
                    format: uri
                events:
                    type: array
                    items:
                        type: string
                is_active:
                    type: boolean
                description:
                    type: string

        WebhookCreatedResponse:
            type: object
            required: [id, url, events, secret, created_at]
            properties:
                id:
                    type: string
                    format: uuid
                url:
                    type: string
                    format: uri
                events:
                    type: array
                    items:
                        type: string
                secret:
                    type: string
                    description: HMAC signing secret for verifying payloads (shown only once)
                created_at:
                    type: string
                    format: date-time

        WebhookResponse:
            type: object
            required: [id, url, events, is_active, created_at]
            properties:
                id:
                    type: string
                    format: uuid
                url:
                    type: string
                    format: uri
                events:
                    type: array
                    items:
                        type: string
                is_active:
                    type: boolean
                description:
                    type: string
                created_at:
                    type: string
                    format: date-time

        WebhookListResponse:
            type: object
            required: [webhooks]
            properties:
                webhooks:
                    type: array
                    items:
                        $ref: "#/components/schemas/WebhookResponse"

        # --- Signing Key Balance ---

        SigningKeyBalanceResponse:
            type: object
            required: [chain, address, balance_wei, balance_display]
            properties:
                chain:
                    type: string
                address:
                    type: string
                balance_wei:
                    type: string
                balance_display:
                    type: string
                tokens:
                    type: array
                    description: Token balances when ?tokens= query param is provided
                    items:
                        type: object
                        properties:
                            contract_address:
                                type: string
                            symbol:
                                type: string
                                nullable: true
                            balance:
                                type: string
                            decimals:
                                type: integer
                                nullable: true

        # --- x402 ---

        PaymentRequirement:
            type: object
            properties:
                x402Version:
                    type: integer
                accepts:
                    type: array
                    items:
                        type: object
                        properties:
                            scheme:
                                type: string
                            network:
                                type: string
                            payTo:
                                type: string
                            price:
                                type: string
                            requiredDeadlineSeconds:
                                type: integer
                description:
                    type: string

        # --- Shroud Activity ---

        ShroudActivityEvent:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                org_id:
                    type: string
                    format: uuid
                agent_id:
                    type: string
                provider:
                    type: string
                model:
                    type: string
                action:
                    type: string
                    description: Action taken (allowed, blocked, warned)
                request_tokens:
                    type: integer
                response_tokens:
                    type: integer
                latency_ms:
                    type: integer
                had_secrets_redacted:
                    type: boolean
                had_pii_detected:
                    type: boolean
                injection_score:
                    type: number
                policy_violations:
                    type: array
                    items:
                        type: string
                # Response-side inspection signals (Shroud v0.5.0+,
                # H-RESP-INSPECT). Optional — pre-v0.5.0 events have them
                # unset; treat as zero / empty.
                response_injection_score:
                    type: number
                    description: Response-side prompt-injection score (0.0–1.0).
                response_context_injection_score:
                    type: number
                    description: Response-side context-injection score (0.0–1.0).
                response_injection_categories:
                    type: array
                    items:
                        type: string
                    description: Category tags emitted by the response-side filters (e.g. `markdown_image_exfil`, `data_uri_blob`, `echoed_instruction`).
                external_urls_flagged:
                    type: array
                    items:
                        type: string
                    description: URLs emitted by the model that were flagged as potential exfil / callback targets.
                unexpected_code_blocks:
                    type: integer
                    description: Number of code fences in the response that were not expected for the agent's allowed task set.
                content_filtered:
                    type: boolean
                    description: True when Shroud rewrote or blocked response content before returning it to the agent.
                metadata:
                    type: object
                timestamp:
                    type: string
                    format: date-time

        IngestShroudActivityRequest:
            type: object
            required: [agent_id, action]
            properties:
                agent_id:
                    type: string
                provider:
                    type: string
                model:
                    type: string
                action:
                    type: string
                request_tokens:
                    type: integer
                    default: 0
                response_tokens:
                    type: integer
                    default: 0
                latency_ms:
                    type: integer
                had_secrets_redacted:
                    type: boolean
                    default: false
                had_pii_detected:
                    type: boolean
                    default: false
                injection_score:
                    type: number
                    default: 0
                policy_violations:
                    type: array
                    items:
                        type: string
                metadata:
                    type: object
                # Response-side inspection signals (Shroud v0.5.0+,
                # H-RESP-INSPECT). Optional for backward compatibility.
                response_injection_score:
                    type: number
                    default: 0
                response_context_injection_score:
                    type: number
                    default: 0
                response_injection_categories:
                    type: array
                    items:
                        type: string
                external_urls_flagged:
                    type: array
                    items:
                        type: string
                unexpected_code_blocks:
                    type: integer
                    default: 0
                content_filtered:
                    type: boolean
                    default: false

        ShroudThreatSummary:
            type: object
            properties:
                total_requests:
                    type: integer
                    format: int64
                total_requests_prev:
                    type: integer
                    format: int64
                blocked_requests:
                    type: integer
                    format: int64
                detectors_triggered:
                    type: integer
                    format: int64
                active_agents:
                    type: integer
                    format: int64
                detectors:
                    type: array
                    items:
                        $ref: "#/components/schemas/ShroudDetectorStats"
                flagged_requests:
                    type: array
                    items:
                        $ref: "#/components/schemas/ShroudFlaggedRequest"

        ShroudDetectorStats:
            type: object
            properties:
                detector:
                    type: string
                detections:
                    type: integer
                    format: int64
                blocks:
                    type: integer
                    format: int64
                actions:
                    type: object
                    properties:
                        blocked:
                            type: integer
                            format: int64
                        warned:
                            type: integer
                            format: int64
                        logged:
                            type: integer
                            format: int64

        ShroudFlaggedRequest:
            type: object
            properties:
                id:
                    type: string
                timestamp:
                    type: string
                    format: date-time
                agent_id:
                    type: string
                agent_name:
                    type: string
                score:
                    type: number
                reason:
                    type: string
                action:
                    type: string
                    enum: [blocked, warned, logged]

        # --- Health ---

        HealthResponse:
            type: object
            properties:
                status:
                    type: string
                    enum: [healthy, degraded]
                version:
                    type: string

        # --- Platform API Schemas ---

        CreatePlatformAppRequest:
            type: object
            required: [name, slug]
            properties:
                name:
                    type: string
                slug:
                    type: string
                    minLength: 3
                    maxLength: 64
                    pattern: "^[a-zA-Z0-9_-]+$"
                description:
                    type: string
                oidc_jwks_url:
                    type: string
                    format: uri
                oidc_issuer:
                    type: string
                    format: uri
                oidc_audience:
                    type: string
                    description: Expected audience claim for OIDC token validation
                redirect_uris:
                    type: array
                    items:
                        type: string
                        format: uri
                billing_model:
                    type: string
                    enum: [platform_pays, user_pays, hybrid]
                    default: platform_pays
                auth_mode:
                    type: string
                    enum: [silent, user_signin, configurable]
                    default: silent
                max_connected_users:
                    type: integer
                    nullable: true
                api_key_expires_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: Optional expiration time for the platform API key.

        UpdatePlatformAppRequest:
            type: object
            properties:
                name:
                    type: string
                description:
                    type: string
                logo_url:
                    type: string
                oidc_jwks_url:
                    type: string
                oidc_issuer:
                    type: string
                oidc_audience:
                    type: string
                    description: Expected audience claim for OIDC token validation
                redirect_uris:
                    type: array
                    items:
                        type: string
                webhook_url:
                    type: string
                billing_model:
                    type: string
                    enum: [platform_pays, user_pays, hybrid]
                auth_mode:
                    type: string
                    enum: [silent, user_signin, configurable]
                max_connected_users:
                    type: integer
                    nullable: true
                is_active:
                    type: boolean
                api_key_expires_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: Optional expiration time for the platform API key. Set to null to clear.

        PlatformAppResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                name:
                    type: string
                slug:
                    type: string
                description:
                    type: string
                logo_url:
                    type: string
                    nullable: true
                api_key_prefix:
                    type: string
                oidc_jwks_url:
                    type: string
                    nullable: true
                oidc_issuer:
                    type: string
                    nullable: true
                oidc_audience:
                    type: string
                    nullable: true
                    description: Expected audience claim for OIDC token validation
                redirect_uris:
                    type: array
                    items:
                        type: string
                webhook_url:
                    type: string
                    nullable: true
                is_active:
                    type: boolean
                billing_model:
                    type: string
                auth_mode:
                    type: string
                max_connected_users:
                    type: integer
                    nullable: true
                connected_users:
                    type: integer
                api_key_expires_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: When the platform API key expires.
                api_key_rotated_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: When the platform API key was last rotated.
                created_at:
                    type: string
                    format: date-time
                updated_at:
                    type: string
                    format: date-time

        PlatformAppCreatedResponse:
            allOf:
                - $ref: "#/components/schemas/PlatformAppResponse"
                - type: object
                  required: [api_key]
                  properties:
                      api_key:
                          type: string
                          description: The platform API key. Save immediately - it cannot be retrieved again.

        CreateTemplateRequest:
            type: object
            required: [name, spec]
            properties:
                name:
                    type: string
                description:
                    type: string
                spec:
                    type: object
                    description: |
                        Template specification defining vault, agents, policies, and signing keys to bootstrap.
                        Top-level fields: `vault` (object with name, description), `agents` (array of agent specs
                        with name, description, shroud_enabled, intents, shroud_config), `policies` (array with
                        vault_ref, principal_ref, paths, permissions, conditions), and `signing_keys` (array of
                        `{ chain }` objects — supported chains: ethereum, bitcoin, solana, xrp, cardano, tron).
                        When `signing_keys` is present, HSM-backed signing keys are auto-provisioned for the
                        bootstrapped agent.

        PlatformTemplateResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                platform_app_id:
                    type: string
                    format: uuid
                name:
                    type: string
                description:
                    type: string
                version:
                    type: integer
                spec:
                    type: object
                is_active:
                    type: boolean
                created_at:
                    type: string
                    format: date-time
                updated_at:
                    type: string
                    format: date-time

        UpsertPlatformUserRequest:
            type: object
            properties:
                subject_token:
                    type: string
                    description: OIDC JWT from the platform's IdP (verified against JWKS)
                subject_token_type:
                    type: string
                    default: "urn:ietf:params:oauth:token-type:jwt"
                email:
                    type: string
                    format: email
                    description: Fallback when subject_token is not provided
                display_name:
                    type: string

        PlatformUserResponse:
            type: object
            properties:
                user_handle:
                    type: string
                    format: uuid
                is_new:
                    type: boolean
                connection_id:
                    type: string
                    format: uuid
                email:
                    type: string
                link_required:
                    $ref: "#/components/schemas/LinkRequiredInfo"

        PlatformUserLinkRequiredResponse:
            type: object
            required: [is_new, email, link_required]
            properties:
                is_new:
                    type: boolean
                    example: false
                email:
                    type: string
                link_required:
                    $ref: "#/components/schemas/LinkRequiredInfo"

        LinkRequiredInfo:
            type: object
            required: [status, reason, authorize_url, app_slug]
            properties:
                status:
                    type: string
                    enum: [link_required]
                reason:
                    type: string
                    example: user_exists_in_other_org
                authorize_url:
                    type: string
                    format: uri
                    description: OAuth authorize URL the platform app should redirect the user to for consent.
                app_slug:
                    type: string

        PlatformConnectedUserResponse:
            type: object
            properties:
                connection_id:
                    type: string
                    format: uuid
                user_id:
                    type: string
                    format: uuid
                external_subject:
                    type: string
                status:
                    type: string
                vault_ids:
                    type: array
                    items:
                        type: string
                        format: uuid
                agent_ids:
                    type: array
                    items:
                        type: string
                        format: uuid
                created_at:
                    type: string
                    format: date-time
                claimed_at:
                    type: string
                    format: date-time
                    nullable: true

        BootstrapRequest:
            type: object
            properties:
                template_id:
                    type: string
                    format: uuid
                    description: Template to use. Falls back to the app's default template.
                return_to:
                    type: string
                    format: uri
                    description: URL to redirect the user to after claiming resources.

        BootstrapResponse:
            type: object
            properties:
                claim_url:
                    type: string
                    format: uri
                claim_token:
                    type: string
                expires_in:
                    type: integer
                    description: Seconds until the claim token expires
                connection_id:
                    type: string
                    format: uuid
                summary:
                    type: object
                    properties:
                        vault_id:
                            type: string
                            format: uuid
                            nullable: true
                        agent_id:
                            type: string
                            format: uuid
                            nullable: true
                        policy_ids:
                            type: array
                            items:
                                type: string
                                format: uuid
                        signing_key_chains:
                            type: array
                            items:
                                type: string
                            description: Chains with provisioned signing keys
                        agent_api_key:
                            type: string
                            nullable: true
                            description: One-time agent API key (ocv_ prefix). Store securely — not retrievable later.
                        signing_keys:
                            type: array
                            description: Provisioned signing key details (chain, address, public key)
                            items:
                                type: object
                                properties:
                                    chain:
                                        type: string
                                    curve:
                                        type: string
                                    public_key:
                                        type: string
                                    address:
                                        type: string

        ConnectedAppResponse:
            type: object
            properties:
                connection_id:
                    type: string
                    format: uuid
                app_name:
                    type: string
                app_slug:
                    type: string
                status:
                    type: string
                vault_ids:
                    type: array
                    items:
                        type: string
                        format: uuid
                agent_ids:
                    type: array
                    items:
                        type: string
                        format: uuid
                created_at:
                    type: string
                    format: date-time

        GrantResourcesRequest:
            type: object
            properties:
                vault_ids:
                    type: array
                    items:
                        type: string
                        format: uuid
                    description: Vault IDs to grant access to
                agent_ids:
                    type: array
                    items:
                        type: string
                        format: uuid
                    description: Agent IDs to grant access to
                allowed_paths:
                    type: array
                    items:
                        type: string
                    default: ["**"]
                    description: Secret path patterns the app can access
                permissions:
                    type: array
                    items:
                        type: string
                    default: ["read"]
                    description: Permissions granted (read, write, rotate)
                expires_at:
                    type: string
                    format: date-time
                    description: Optional grant expiration

        GrantResponse:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                vault_id:
                    type: string
                    format: uuid
                allowed_paths:
                    type: array
                    items:
                        type: string
                permissions:
                    type: array
                    items:
                        type: string
                expires_at:
                    type: string
                    format: date-time
                    nullable: true
                created_at:
                    type: string
                    format: date-time

        GrantResourcesResponse:
            type: object
            properties:
                connection_id:
                    type: string
                    format: uuid
                grants:
                    type: array
                    items:
                        $ref: "#/components/schemas/GrantResponse"
                vault_ids:
                    type: array
                    items:
                        type: string
                        format: uuid
                agent_ids:
                    type: array
                    items:
                        type: string
                        format: uuid

        GrantListResponse:
            type: object
            properties:
                grants:
                    type: array
                    items:
                        $ref: "#/components/schemas/GrantResponse"

        ClaimPreviewResponse:
            type: object
            properties:
                app_name:
                    type: string
                app_slug:
                    type: string
                app_logo_url:
                    type: string
                    nullable: true
                auth_mode:
                    type: string
                vault_ids:
                    type: array
                    items:
                        type: string
                        format: uuid
                agent_ids:
                    type: array
                    items:
                        type: string
                        format: uuid
                policy_count:
                    type: integer
                status:
                    type: string
                already_claimed:
                    type: boolean
                expired:
                    type: boolean
                return_to:
                    type: string
                    nullable: true

        ClaimRedeemResponse:
            type: object
            properties:
                status:
                    type: string
                connection_id:
                    type: string
                    format: uuid
                vault_ids:
                    type: array
                    items:
                        type: string
                        format: uuid
                agent_ids:
                    type: array
                    items:
                        type: string
                        format: uuid
                return_to:
                    type: string
                    nullable: true
                dashboard_url:
                    type: string

        # --- Mobile Companion App schemas ---

        RegisterDeviceRequest:
            type: object
            required: [name, platform, public_key_pem]
            properties:
                name:
                    type: string
                    description: Human-readable device name (e.g. "Kevin's iPhone")
                    example: My iPhone
                platform:
                    type: string
                    enum: [ios, android]
                public_key_pem:
                    type: string
                    description: PEM-encoded public key for step-up challenge signing
                attestation_blob:
                    type: string
                    description: Optional platform attestation (Apple DeviceCheck / Android SafetyNet)

        RegisterDeviceResponse:
            type: object
            required: [device_id, attestation_verified]
            properties:
                device_id:
                    type: string
                    format: uuid
                attestation_verified:
                    type: boolean

        DeviceListResponse:
            type: object
            required: [devices]
            properties:
                devices:
                    type: array
                    items:
                        $ref: "#/components/schemas/DeviceResponse"

        DeviceResponse:
            type: object
            required: [id, name, platform, attestation_verified, created_at]
            properties:
                id:
                    type: string
                    format: uuid
                name:
                    type: string
                platform:
                    type: string
                attestation_verified:
                    type: boolean
                last_used_at:
                    type: string
                    format: date-time
                    nullable: true
                created_at:
                    type: string
                    format: date-time

        CreateDeviceChallengeRequest:
            type: object
            required: [action, target_id]
            properties:
                action:
                    type: string
                    description: The action this challenge authorizes (e.g. "approve_transaction")
                target_id:
                    type: string
                    description: ID of the resource the action targets

        DeviceChallengeResponse:
            type: object
            required: [challenge_nonce, expires_at, action_bound_hash]
            properties:
                challenge_nonce:
                    type: string
                expires_at:
                    type: string
                    format: date-time
                action_bound_hash:
                    type: string
                    description: SHA-256 binding the challenge to the requested action and target

        AttestDeviceChallengeRequest:
            type: object
            required: [challenge_nonce, signature]
            properties:
                challenge_nonce:
                    type: string
                signature:
                    type: string
                    description: Signature over the challenge nonce using the device's private key

        AttestDeviceChallengeResponse:
            type: object
            required: [step_up_token, expires_at]
            properties:
                step_up_token:
                    type: string
                    description: Short-lived token authorizing the bound action
                expires_at:
                    type: string
                    format: date-time

        RegisterPushTokenRequest:
            type: object
            required: [token, platform]
            properties:
                token:
                    type: string
                    description: Push notification token from APNs or FCM
                platform:
                    type: string
                    enum: [apns, fcm]

        DecideApprovalRequest:
            type: object
            required: [decision]
            properties:
                decision:
                    type: string
                    enum: [approve, reject]
                reason:
                    type: string
                    description: Optional human-readable reason for the decision

        ApprovalResponse:
            type: object
            required: [id, org_id, user_id, action, target_type, target_id, risk_tier, status, summary, created_at]
            properties:
                id:
                    type: string
                    format: uuid
                org_id:
                    type: string
                    format: uuid
                user_id:
                    type: string
                    format: uuid
                agent_id:
                    type: string
                    format: uuid
                    nullable: true
                action:
                    type: string
                target_type:
                    type: string
                target_id:
                    type: string
                risk_tier:
                    type: integer
                    minimum: 1
                    maximum: 3
                status:
                    type: string
                    enum: [pending, approved, rejected, expired]
                summary:
                    type: object
                    description: Structured summary of the action requiring approval
                reason:
                    type: string
                    nullable: true
                decision_reason:
                    type: string
                    nullable: true
                decided_by:
                    type: string
                    format: uuid
                    nullable: true
                decided_at:
                    type: string
                    format: date-time
                    nullable: true
                expires_at:
                    type: string
                    format: date-time
                    nullable: true
                created_at:
                    type: string
                    format: date-time

        # --- Email OTP ---

        EmailOtpVerifyResponse:
            type: object
            required: [token, user_id, org_id, is_new_user, email]
            properties:
                token:
                    type: string
                    description: JWT access token
                user_id:
                    type: string
                    format: uuid
                org_id:
                    type: string
                    format: uuid
                is_new_user:
                    type: boolean
                email:
                    type: string
                    format: email
                wallet_address:
                    type: string
                    nullable: true
                    description: Ethereum address if auto_provision_chains included an EVM chain

        # --- OAuth ---

        OAuthConsentResponse:
            type: object
            required: [app_name, app_slug, scopes, redirect_uri, already_consented]
            properties:
                app_name:
                    type: string
                app_slug:
                    type: string
                app_logo_url:
                    type: string
                    format: uri
                    nullable: true
                scopes:
                    type: array
                    items: { type: string }
                redirect_uri:
                    type: string
                    format: uri
                already_consented:
                    type: boolean

        OAuthTokenResponse:
            type: object
            required: [access_token, token_type, expires_in, scope]
            properties:
                access_token:
                    type: string
                token_type:
                    type: string
                    enum: [Bearer]
                expires_in:
                    type: integer
                    description: Token lifetime in seconds
                id_token:
                    type: string
                    nullable: true
                    description: OIDC ID token (when openid scope was granted)
                scope:
                    type: string

        OAuthUserInfoResponse:
            type: object
            required: [sub, email]
            properties:
                sub:
                    type: string
                    format: uuid
                email:
                    type: string
                    format: email
                name:
                    type: string
                    nullable: true
                wallet_address:
                    type: string
                    nullable: true

        # --- Spend Policies ---

        CreateSpendPolicyRequest:
            type: object
            properties:
                user_id:
                    type: string
                    format: uuid
                    description: Scope to a specific user (app-level policies only)
                to_allowlist:
                    type: array
                    items: { type: string }
                    description: Permitted destination addresses (empty = unrestricted)
                to_denylist:
                    type: array
                    items: { type: string }
                    description: Blocked destination addresses
                max_value_per_tx_eth:
                    type: string
                    description: Maximum value per transaction in ETH (decimal string)
                daily_limit_eth:
                    type: string
                    description: Rolling 24h spend cap in ETH (decimal string)
                allowed_chains:
                    type: array
                    items: { type: string }
                    description: Chains the user may transact on (empty = all enabled)
                allowed_tokens:
                    type: array
                    items: { type: string }
                    description: Permitted ERC-20 token contract addresses
                max_transactions_per_day:
                    type: integer
                    description: Maximum number of transactions per 24h window

        SpendPolicyResponse:
            type: object
            required: [id, platform_app_id, created_at]
            properties:
                id:
                    type: string
                    format: uuid
                platform_app_id:
                    type: string
                    format: uuid
                user_id:
                    type: string
                    format: uuid
                    nullable: true
                to_allowlist:
                    type: array
                    items: { type: string }
                to_denylist:
                    type: array
                    items: { type: string }
                max_value_per_tx_eth:
                    type: string
                    nullable: true
                daily_limit_eth:
                    type: string
                    nullable: true
                allowed_chains:
                    type: array
                    items: { type: string }
                allowed_tokens:
                    type: array
                    items: { type: string }
                max_transactions_per_day:
                    type: integer
                    nullable: true
                created_at:
                    type: string
                    format: date-time

        # --- Risk Engine ---

        RiskEvent:
            type: object
            required: [id, occurred_at, principal_type, principal_id, org_id, event_type, payload, created_at]
            properties:
                id:
                    type: string
                    format: uuid
                occurred_at:
                    type: string
                    format: date-time
                principal_type:
                    type: string
                    enum: [user, agent]
                principal_id:
                    type: string
                    format: uuid
                org_id:
                    type: string
                    format: uuid
                event_type:
                    type: string
                    description: "Risk event type (e.g. first_seen, geo_velocity, honeytoken_access)"
                ip:
                    type: string
                    nullable: true
                asn:
                    type: integer
                    nullable: true
                asn_org:
                    type: string
                    nullable: true
                country_code:
                    type: string
                    nullable: true
                region:
                    type: string
                    nullable: true
                city:
                    type: string
                    nullable: true
                latitude:
                    type: number
                    nullable: true
                longitude:
                    type: number
                    nullable: true
                user_agent:
                    type: string
                    nullable: true
                severity:
                    type: string
                    nullable: true
                    description: "Computed severity at event time (low, medium, high, critical)"
                payload:
                    type: object
                    additionalProperties: true
                created_at:
                    type: string
                    format: date-time

        RiskEventListResponse:
            type: object
            required: [events]
            properties:
                events:
                    type: array
                    items:
                        $ref: "#/components/schemas/RiskEvent"

        RiskVerdictReason:
            type: object
            required: [detector, severity, description]
            properties:
                detector:
                    type: string
                severity:
                    type: string
                description:
                    type: string
                metadata:
                    type: object
                    additionalProperties: true

        RiskVerdict:
            type: object
            required: [principal_type, principal_id, org_id, score, severity, reasons, computed_at, expires_at]
            properties:
                principal_type:
                    type: string
                principal_id:
                    type: string
                    format: uuid
                org_id:
                    type: string
                    format: uuid
                score:
                    type: number
                    description: Composite risk score (0.0 – 100.0)
                severity:
                    type: string
                    enum: [low, medium, high, critical]
                reasons:
                    type: array
                    items:
                        $ref: "#/components/schemas/RiskVerdictReason"
                computed_at:
                    type: string
                    format: date-time
                expires_at:
                    type: string
                    format: date-time

        RiskVerdictListResponse:
            type: object
            required: [verdicts]
            properties:
                verdicts:
                    type: array
                    items:
                        $ref: "#/components/schemas/RiskVerdict"

        Honeytoken:
            type: object
            required: [id, vault_id, org_id, secret_path, created_by, created_at, triggered_count]
            properties:
                id:
                    type: string
                    format: uuid
                vault_id:
                    type: string
                    format: uuid
                org_id:
                    type: string
                    format: uuid
                secret_path:
                    type: string
                created_by:
                    type: string
                    format: uuid
                created_at:
                    type: string
                    format: date-time
                notes:
                    type: string
                    nullable: true
                triggered_count:
                    type: integer
                last_triggered_at:
                    type: string
                    format: date-time
                    nullable: true

        CreateHoneytokenRequest:
            type: object
            required: [vault_id, secret_path]
            properties:
                vault_id:
                    type: string
                    format: uuid
                secret_path:
                    type: string
                    description: Vault secret path to monitor as a canary
                notes:
                    type: string
                    description: Optional human-readable notes about this honeytoken

        HoneytokenListResponse:
            type: object
            required: [honeytokens]
            properties:
                honeytokens:
                    type: array
                    items:
                        $ref: "#/components/schemas/Honeytoken"

        # --- Execution Intents ---

        CredentialSource:
            type: object
            required: [type]
            description: Credential source — inline value (stored in __agent-keys) or live pointer to a vault secret (resolved at execution time).
            discriminator:
                propertyName: type
            properties:
                type:
                    type: string
                    enum: [inline, vault_ref]
                value:
                    type: object
                    additionalProperties: true
                    description: For inline — the credential value object.
                vault_id:
                    type: string
                    format: uuid
                    description: For vault_ref — the vault containing the referenced secret.
                path:
                    type: string
                    description: For vault_ref — the secret path in the vault.

        CreateBindingRequest:
            type: object
            required: [name, binding_type]
            properties:
                name:
                    type: string
                binding_type:
                    type: string
                    enum: [http, graphql, postgres, mysql, redis, grpc, smtp, cloud_sdk, s3, custom]
                config:
                    type: object
                    additionalProperties: true
                guardrails:
                    type: object
                    additionalProperties: true
                credential:
                    type: object
                    additionalProperties: true
                    description: "Legacy: inline credential value. Use credential_source for new integrations."
                credential_source:
                    $ref: "#/components/schemas/CredentialSource"

        UpdateBindingRequest:
            type: object
            properties:
                config:
                    type: object
                    additionalProperties: true
                guardrails:
                    type: object
                    additionalProperties: true
                is_active:
                    type: boolean
                credential:
                    type: object
                    additionalProperties: true
                    description: "Legacy: inline credential value."
                credential_source:
                    $ref: "#/components/schemas/CredentialSource"

        BindingResponse:
            type: object
            required: [id, agent_id, binding_type, name, is_active, created_at, updated_at]
            properties:
                id:
                    type: string
                    format: uuid
                agent_id:
                    type: string
                    format: uuid
                binding_type:
                    type: string
                    enum: [http, graphql, postgres, mysql, redis, grpc, smtp, cloud_sdk, s3, custom]
                name:
                    type: string
                config:
                    type: object
                    additionalProperties: true
                guardrails:
                    type: object
                    additionalProperties: true
                is_active:
                    type: boolean
                credential_set:
                    type: boolean
                    description: Whether a credential is stored for this binding. The value itself is never returned.
                credential_source_type:
                    type: string
                    enum: [inline, vault_ref]
                    nullable: true
                    description: How the credential is sourced — inline (HSM-encrypted copy) or vault_ref (live pointer).
                credential_vault_id:
                    type: string
                    format: uuid
                    nullable: true
                    description: For vault_ref credentials — the vault containing the referenced secret.
                credential_path:
                    type: string
                    nullable: true
                    description: For vault_ref credentials — the secret path in the referenced vault.
                created_at:
                    type: string
                    format: date-time
                updated_at:
                    type: string
                    format: date-time

        TestBindingResponse:
            type: object
            required: [success, latency_ms]
            properties:
                success:
                    type: boolean
                latency_ms:
                    type: integer
                error:
                    type: string
                    nullable: true

        ExecuteRequest:
            type: object
            required: [binding, intent_type, params]
            properties:
                binding:
                    type: string
                    description: Binding name or ID to execute against
                intent_type:
                    type: string
                    description: Type of execution intent (e.g. http_request, graphql_query)
                execution_mode:
                    type: string
                    enum: [vault, tee]
                    default: vault
                    description: Where execution runs (vault = server-side, tee = Shroud TEE)
                params:
                    type: object
                    additionalProperties: true
                    description: Intent-specific parameters

        ExecuteResponse:
            type: object
            required: [execution_id, status, duration_ms, redactions_applied]
            properties:
                execution_id:
                    type: string
                    format: uuid
                status:
                    type: string
                result:
                    type: object
                    additionalProperties: true
                    nullable: true
                error:
                    type: string
                    nullable: true
                duration_ms:
                    type: integer
                redactions_applied:
                    type: integer
                execution_surface:
                    type: string
                    enum: [vault, tee]
                    description: Where the intent actually ran. Reported truthfully — never claims TEE when it ran in the Vault.

        ExecutionEventResponse:
            type: object
            required: [id, agent_id, binding_id, intent_type, execution_mode, status, duration_ms, redactions_applied, created_at]
            properties:
                id:
                    type: string
                    format: uuid
                agent_id:
                    type: string
                    format: uuid
                binding_id:
                    type: string
                    format: uuid
                intent_type:
                    type: string
                execution_mode:
                    type: string
                status:
                    type: string
                request_summary:
                    type: object
                    additionalProperties: true
                    nullable: true
                result_summary:
                    type: object
                    additionalProperties: true
                    nullable: true
                error_message:
                    type: string
                    nullable: true
                duration_ms:
                    type: integer
                cost_cents:
                    type: integer
                    nullable: true
                redactions_applied:
                    type: integer
                created_at:
                    type: string
                    format: date-time