components:
    schemas:
        AgentCard:
            description: A2A Agent Card per the A2A protocol specification
            type: object
        AgentSkillNotFound:
            properties:
                detail:
                    type: string
            type: object
        CreateWalletRequest:
            properties:
                chain_selector:
                    description: |
                        Chain selector (decimal string) for the chain wallet. Must be a chain
                        supported by this gateway deployment.
                    example: "16015286601757825753"
                    type: string
            type: object
        CreateWalletResponse:
            properties:
                agent_address:
                    description: EIP-191 signer (agent) address, lowercased.
                    type: string
                chain_selector:
                    description: |
                        Chain selector (decimal string) for the provisioned wallet.
                    example: "16015286601757825753"
                    type: string
                wallet_address:
                    description: Deployed on-chain account-abstraction wallet for this chain.
                    type: string
            type: object
        DirectOperationRequest:
            properties:
                chain_selector:
                    description: |
                        Chain selector (decimal string) for the target chain. Must be a chain
                        supported by this gateway deployment.
                    example: "16015286601757825753"
                    type: string
                deadline:
                    description: Unix timestamp for signature expiry; 0 means no expiration.
                    example: 0
                    format: int64
                    type: integer
                nonce:
                    description: |
                        Base-10 integer string in uint256 range. Same value as EIP-712 `Operation.id`
                        and `wallet_operation_id`.
                    example: "170141183460469231731687303715884105727"
                    type: string
                signature:
                    description: EIP-712 ECDSA signature (hex) over the operation typed data.
                    example: 0x...
                    type: string
                transactions:
                    items:
                        $ref: '#/components/schemas/TransactionInput'
                    minItems: 1
                    type: array
            required:
                - chain_selector
                - nonce
                - transactions
                - signature
            type: object
        ErrorDetail:
            properties:
                category:
                    type: string
                code:
                    type: string
                details: {}
                message:
                    type: string
                request_id:
                    type: string
                retry:
                    $ref: '#/components/schemas/RetryInfo'
                timestamp:
                    format: date-time
                    type: string
            required:
                - code
                - category
                - message
                - timestamp
                - request_id
            type: object
        ErrorResponse:
            properties:
                error:
                    $ref: '#/components/schemas/ErrorDetail'
            required:
                - error
            type: object
        ExecuteWorkflowRequest:
            properties:
                params:
                    additionalProperties: true
                    description: |
                        Fields for this workflow are defined in `GET /v1/catalog/{name}` → `input_schema`.
                    example:
                        amount: "1000000"
                        chain_selector: "16015286601757825753"
                        to_address: 0x2222222222222222222222222222222222222222
                        token_address: 0x1111111111111111111111111111111111111111
                    type: object
            required:
                - params
            type: object
        ListNetworksResponse:
            properties:
                has_more:
                    type: boolean
                items:
                    items:
                        properties:
                            chain_family:
                                type: string
                            chain_id:
                                type: string
                            chain_selector:
                                type: string
                            name:
                                type: string
                        type: object
                    type: array
            type: object
        ListWalletsResponse:
            properties:
                wallets:
                    items:
                        $ref: '#/components/schemas/ListedWalletResponse'
                    type: array
            type: object
        ListedWalletResponse:
            properties:
                chain_selector:
                    type: string
                created_at:
                    format: date-time
                    type: string
                wallet_address:
                    type: string
            type: object
        OperationStatus:
            properties:
                address:
                    type: string
                chain_selector:
                    type: string
                created_at:
                    format: int64
                    type: integer
                deadline:
                    description: |
                        Operation expiry hint in the typed data (0 = no expiry in typical deployments).
                    format: int64
                    type: integer
                eip712:
                    additionalProperties: true
                    description: |
                        EIP-712 typed data for local signing. Present when `transactions` is non-empty
                        and the run targets an EVM chain. Sign the object the gateway returns; do not
                        build typed data from scratch.
                    type: object
                operation_id:
                    type: string
                result:
                    $ref: '#/components/schemas/WorkflowResult'
                signature:
                    type: string
                status:
                    description: |
                        Lifecycle state. For workflow-backed chain batches, `pending_signature` means
                        EIP-712 signing is still required. Typical values include `accepted`, `sent`, `broadcasting`,
                        `confirmed`, and `failed` for transactions; workflows may use `accepted`,
                        `completed`, `failed`, or `timed_out`.
                    type: string
                transactions:
                    items:
                        $ref: '#/components/schemas/TransactionInput'
                    type: array
                type:
                    description: Operation kind — on-chain transaction batch or asynchronous workflow.
                    enum:
                        - transaction
                        - workflow
                    type: string
                updated_at:
                    format: int64
                    type: integer
                wallet_operation_id:
                    description: |
                        Decimal string uint256 used as EIP-712 `Operation.id`. For `type=transaction`,
                        this is the external wallet operation id. For `type=workflow`, it is derived
                        from the gateway `operation_id`. Sign the returned `eip712` object and submit
                        via `POST /v1/operations/{id}/submit`.
                    type: string
                workflow_name:
                    type: string
            type: object
        PatchRegistrationRequest:
            description: |
                At least one of `tos_signature` or a new `execution_mode` must be supplied (same mode as stored is not an update).
            properties:
                execution_mode:
                    description: Omit to leave unchanged; set to switch modes.
                    enum:
                        - guardrailed
                        - unrestricted
                    type: string
                tos_signature:
                    description: EIP-712 signature over the current ToS version's typed data (omit if only changing execution_mode).
                    example: 0xabcdef...
                    type: string
            type: object
        RegisterRequest:
            properties:
                execution_mode:
                    description: |
                        Applies only when creating a new agent; defaults to `guardrailed`.
                        To change mode later, use `PATCH /v1/register`.
                    enum:
                        - guardrailed
                        - unrestricted
                    type: string
                tos_signature:
                    description: EIP-712 signature over the current ToS version's typed data
                    example: 0xabcdef...
                    type: string
            required:
                - tos_signature
            type: object
        RegistrationResponse:
            properties:
                agent_address:
                    description: EIP-191 signer (agent) address, lowercased.
                    type: string
                agent_id:
                    type: string
                execution_mode:
                    description: The effective execution mode for this agent.
                    enum:
                        - guardrailed
                        - unrestricted
                    type: string
            type: object
        RetryInfo:
            properties:
                guidance:
                    type: string
                retryable:
                    type: boolean
                suggested_delay_ms:
                    type: integer
            type: object
        StreamsReportResponse:
            properties:
                feedID:
                    description: 0x-prefixed hex-encoded feed ID
                    example: 0x00036f6a26474b3a0da04ae642640db0e30e856e0c19a0a23a80ecc75fa55e12
                    type: string
                fullReport:
                    description: 0x-prefixed hex-encoded full report payload
                    type: string
                observationsTimestamp:
                    description: Timestamp when observations were made
                    format: uint64
                    type: integer
                validFromTimestamp:
                    description: Earliest timestamp this report is valid from
                    format: uint64
                    type: integer
            type: object
        SubmitOperationResponse:
            properties:
                operation_id:
                    type: string
                status:
                    type: string
            type: object
        SubmitSignatureRequest:
            properties:
                signature:
                    description: EIP-712 signature for the operation batch
                    type: string
            required:
                - signature
            type: object
        SupportedFeeToken:
            properties:
                address:
                    example: 0xc4bF5CbDaBE595361438F8c6a187bDc330539c60
                    type: string
                name:
                    example: GHO Token
                    type: string
                symbol:
                    example: GHO
                    type: string
            required:
                - symbol
                - name
                - address
            type: object
        SupportedFeeTokensForChain:
            properties:
                chain_name:
                    example: Ethereum Sepolia
                    type: string
                chain_selector:
                    example: "16015286601757825753"
                    type: string
                tokens:
                    items:
                        $ref: '#/components/schemas/SupportedFeeToken'
                    type: array
            required:
                - chain_selector
                - chain_name
                - tokens
            type: object
        TermsOfServiceResponse:
            properties:
                content_hash:
                    description: 32-byte content hash as lowercase hex without 0x prefix (from database)
                    type: string
                effective_at:
                    description: When this ToS version became effective (RFC3339 UTC)
                    format: date-time
                    type: string
                typed_data:
                    description: EIP-712 v4 payload suitable for eth_signTypedData / eth_account
                    properties:
                        domain:
                            properties:
                                chainId:
                                    format: int64
                                    type: integer
                                name:
                                    type: string
                                version:
                                    type: string
                            type: object
                        message:
                            properties:
                                contentHash:
                                    description: 0x-prefixed 32-byte hex
                                    type: string
                                url:
                                    type: string
                                version:
                                    type: string
                            type: object
                        primaryType:
                            example: ToSAgreement
                            type: string
                        types:
                            additionalProperties:
                                items:
                                    properties:
                                        name:
                                            type: string
                                        type:
                                            type: string
                                    type: object
                                type: array
                            type: object
                    required:
                        - types
                        - primaryType
                        - domain
                        - message
                    type: object
                url:
                    description: Canonical ToS URL included in the EIP-712 message
                    type: string
                version:
                    description: Active ToS row version (matches EIP-712 message.version)
                    type: integer
            required:
                - version
                - content_hash
                - url
                - typed_data
            type: object
        TransactionInput:
            properties:
                data:
                    type: string
                to:
                    type: string
                value:
                    type: string
            required:
                - to
                - value
                - data
            type: object
        WorkflowCatalogDetail:
            properties:
                auth:
                    description: Authentication, Terms of Service, and payment requirements for endpoint-backed skills.
                    example:
                        - EIP-191
                        - ToS
                        - x402
                    items:
                        type: string
                    type: array
                chain_selector_price_overrides_usdc:
                    additionalProperties:
                        description: USDC amount as a decimal string.
                        type: string
                    description: Optional workflow x402 price overrides keyed by chain selector.
                    example:
                        "16015286601757825753": "0.05"
                    type: object
                description:
                    type: string
                execute_endpoint:
                    description: Full method and path to execute this catalog item.
                    example: POST /v1/operations/token-transfer
                    type: string
                input_schema:
                    additionalProperties:
                        $ref: '#/components/schemas/WorkflowInputFieldMeta'
                    type: object
                kind:
                    description: Catalog item kind.
                    enum:
                        - workflow
                        - endpoint
                    type: string
                name:
                    type: string
                price_tier:
                    description: Payment tier for endpoint-backed skills when the exact configured price is deployment-specific.
                    example: read
                    type: string
                price_usdc:
                    description: x402 per-execution USDC price for this workflow (string decimal, e.g. "0.01").
                    type: string
                response_shape:
                    additionalProperties: true
                    description: Example shape returned by endpoint-backed skills.
                    example:
                        report: '...'
                    type: object
                supported_fee_tokens:
                    description: Per-chain CCIP fee token options for bridge workflows, when configured by the gateway.
                    items:
                        $ref: '#/components/schemas/SupportedFeeTokensForChain'
                    type: array
            required:
                - name
                - description
                - input_schema
                - execute_endpoint
            type: object
        WorkflowCatalogResponse:
            items:
                $ref: '#/components/schemas/WorkflowCatalogSummary'
            type: array
        WorkflowCatalogSummary:
            properties:
                description:
                    type: string
                name:
                    type: string
            required:
                - name
                - description
            type: object
        WorkflowInputFieldMeta:
            properties:
                description:
                    type: string
                enum:
                    items:
                        type: string
                    type: array
                required:
                    type: boolean
                type:
                    type: string
            required:
                - type
                - required
            type: object
        WorkflowResult:
            properties:
                output:
                    additionalProperties: true
                    type: object
                summary:
                    type: string
            type: object
    securitySchemes:
        eip191Address:
            description: Checksummed or lower-cased EVM address of the signer (must match recovered EIP-191 signer).
            in: header
            name: X-Agent-Address
            type: apiKey
        eip191Signature:
            description: EIP-191 personal_sign hex signature (65 bytes, 0x-prefixed).
            in: header
            name: X-Agent-Signature
            type: apiKey
        eip191Timestamp:
            description: Unix timestamp in seconds (decimal string), within 5 minutes of server time.
            in: header
            name: X-Agent-Timestamp
            type: apiKey
        x402Payment:
            description: x402 payment header containing a USDC micro-payment settlement proof.
            in: header
            name: X-PAYMENT
            type: apiKey
info:
    contact:
        name: Chainlink
        url: https://chain.link
    description: |
        Chainlink for Agents API for blockchain operations, catalog workflows, optional Data Streams,
        and bundled skill guidance (`GET /v1/skills`, `/v1/skills/bundle` and `/v1/skills/file/...`).

        **Dual Lanes**
        By default, agents are registered with `execution_mode=guardrailed` and can only execute
        catalog workflows. Agents registered with `execution_mode=unrestricted` can also submit
        direct pre-signed transaction batches via `POST /v1/operations/direct`. You should alwayws prefer to
        stay in guardrail mode. First check all available skills to see if you can solve your use case.
        Ask your human before using unrestricted mode.

        **Authentication**
        1. **EIP-191 request signing** – On each protected call, sign a canonical UTF-8 message
           with `personal_sign` and send `X-Agent-Address`, `X-Agent-Signature`, and
           `X-Agent-Timestamp` (unix seconds). The message is
           `METHOD path[?raw_query]\\ntimestamp` and, when a JSON body is present,
           a third line `0x` + hex(SHA256(body)).
        2. **x402 (USDC)** – Where a route requires payment (registration, writes, workflows),
           also attach the x402 `PAYMENT-SIGNATURE` header per the 402 challenge.

        Operations are scoped automatically to the authenticated agent.

        **Agent onboarding**
        Agents must be registered before accessing protected routes.
        Complete registration with `POST /v1/register`.
    title: Chainlink for Agents
    version: 0.2.1
openapi: 3.0.3
paths:
    /.well-known/agent.json:
        get:
            description: |
                Returns the gateway's A2A Agent Card containing capabilities,
                pricing, authentication model, endpoint URLs, and dynamic health
                status. No authentication required.
            operationId: getAgentCard
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AgentCard'
                    description: A2A Agent Card
                    headers:
                        Cache-Control:
                            schema:
                                example: public, max-age=60
                                type: string
            summary: A2A Agent Card
            tags:
                - Discovery
    /v1/catalog:
        get:
            description: |
                Returns a lightweight catalog of workflows and endpoint-backed skills for this gateway build:
                name and description only. Use `GET /v1/catalog/{name}` for input fields, pricing,
                and execute endpoint.
                No authentication required.
            operationId: getCatalog
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowCatalogResponse'
                    description: Lightweight workflow and capability catalog
            security: []
            summary: Workflow and capability catalog
            tags:
                - Discovery
    /v1/catalog/{name}:
        get:
            description: |
                Returns public execution metadata for one workflow or endpoint-backed skill, including
                `input_schema`, pricing metadata, and the full execute endpoint. Workflows use
                `POST /v1/operations/{id}`; endpoint-backed skills include their full REST path.
                (Direct client batches use `POST /v1/operations/direct`; catalog workflow names never include `direct`.)
                Workflows that need a chain declare `params.chain_selector`; use `GET /v1/networks`
                for selector values.
                No authentication required.
            operationId: getCatalogItem
            parameters:
                - description: Catalog item name from `GET /v1/catalog`.
                  in: path
                  name: name
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowCatalogDetail'
                    description: Catalog item execution metadata
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Catalog item not found
            security: []
            summary: Catalog item execution metadata
            tags:
                - Discovery
    /v1/networks:
        get:
            description: |
                List blockchain networks supported by this deployment. The operator may limit
                which built-in entries are exposed; if unset, all built-in testnets for this
                build are listed.
            operationId: listNetworks
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListNetworksResponse'
                    description: Network list
            security:
                - eip191Address: []
                  eip191Signature: []
                  eip191Timestamp: []
            summary: List supported networks
            tags:
                - Discovery
    /v1/openapi.yaml:
        get:
            description: |
                Returns this OpenAPI 3.0 specification. No authentication required.
            operationId: getOpenAPISpec
            responses:
                "200":
                    content:
                        application/x-yaml:
                            schema:
                                type: string
                    description: OpenAPI YAML document
            summary: OpenAPI specification
            tags:
                - Discovery
    /v1/operations:
        get:
            description: |
                List operations for the authenticated agent. Channel and address
                scoping are resolved from agent identity.
            operationId: listOperations
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    has_more:
                                        type: boolean
                                    items:
                                        items:
                                            $ref: '#/components/schemas/OperationStatus'
                                        type: array
                                type: object
                    description: Operation list
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Registration incomplete
            security:
                - eip191Address: []
                  eip191Signature: []
                  eip191Timestamp: []
            summary: List operations
            tags:
                - Operations
    /v1/operations/{id}:
        get:
            description: |
                Retrieve the current status of a gateway operation. The path `id` is the
                gateway `operation_id` (UUID) returned from workflow execute, or direct operation.
                Scoping is resolved from the authenticated agent's identity.
            operationId: getOperationStatus
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/OperationStatus'
                    description: Operation status snapshot
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Operation not found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Registration incomplete
                "502":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Upstream service unavailable
            security:
                - eip191Address: []
                  eip191Signature: []
                  eip191Timestamp: []
            summary: Get operation status
            tags:
                - Operations
        parameters:
            - description: |
                For **GET**: gateway operation id (UUID). For **POST**: a workflow `name` from `GET /v1/catalog` (not a UUID).
              in: path
              name: id
              required: true
              schema:
                type: string
        post:
            description: |
                Starts an asynchronous workflow. The path `id` is the **workflow name** (from the catalog), not
                a UUID. Required x402 amount is per workflow. On rate limit (429) or overload (503), payment
                is not settled. Use `GET /v1/operations/{id}` to poll; when the result includes
                on-chain steps, `status` becomes `pending_signature` until you call `POST /v1/operations/{id}/submit`.
            operationId: executeWorkflow
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ExecuteWorkflowRequest'
                required: true
            responses:
                "202":
                    content:
                        application/json:
                            schema:
                                properties:
                                    operation_id:
                                        type: string
                                    status:
                                        example: accepted
                                        type: string
                                type: object
                    description: Workflow execution accepted
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "402":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Payment required
                "403":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: ToS signature required
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unknown workflow name
                "429":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Rate limited — retry after `Retry-After`
                "502":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Upstream workflow service unavailable or execution rejected
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Service capacity exceeded
            security:
                - eip191Address: []
                  eip191Signature: []
                  eip191Timestamp: []
                  x402Payment: []
            summary: Execute a registered CRE workflow
            tags:
                - Operations
    /v1/operations/{id}/submit:
        post:
            description: |
                Submits the `signature` after a **workflow** has completed and produced an on-chain
                transaction batch in its result (calldata is never accepted from the client in this endpoint).
                Only the same agent that created the operation may call this. The path `id` is the **gateway**
                `operation_id` (UUID) from the execute response. After success, the operation is queued for the
                execution backend with that signature. **Direct** (`POST /v1/operations/direct`) operations are
                submitted with a signature in the direct request body and do not use this endpoint.
            operationId: submitSignedOperation
            parameters:
                - description: Gateway `operation_id` (UUID) from `POST /v1/operations/{workflowName}` (execute workflow).
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/SubmitSignatureRequest'
                required: true
            responses:
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SubmitOperationResponse'
                    description: Signature accepted; operation continues processing
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Operation not found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Already submitted or not ready for submit
                "502":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Upstream service unavailable
            security:
                - eip191Address: []
                  eip191Signature: []
                  eip191Timestamp: []
            summary: Submit EIP-712 signature for a pending workflow operation
            tags:
                - Operations
    /v1/operations/direct:
        post:
            description: |
                Submits a client-built transaction batch with an EIP-712 signature over the operation
                (`nonce` is Operation.id / `wallet_operation_id`; `deadline` is Unix seconds, 0 = none).
                Requires `execution_mode=unrestricted`.
                Returns an `operation_id` (UUID) for polling `GET /v1/operations/{id}`; this ID is for
                tracking only and is distinct from `nonce`.
            operationId: createDirectOperation
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/DirectOperationRequest'
                required: true
            responses:
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SubmitOperationResponse'
                    description: Direct operation accepted
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "402":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Payment required
                "403":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Execution mode forbidden
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Registration incomplete
                "502":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Upstream service unavailable
            security:
                - eip191Address: []
                  eip191Signature: []
                  eip191Timestamp: []
                  x402Payment: []
            summary: Submit a presigned direct transaction batch
            tags:
                - Operations
    /v1/register:
        patch:
            description: |
                For an **existing** agent only. Same EIP-191 and x402 payment requirements as `POST /v1/register`.

                Provide `tos_signature` to record a new ToS agreement, `execution_mode` to change mode (omit fields you are not updating).
                At least one effective change is required (re-sending the same `execution_mode` alone returns 400).

                Response `200` returns the current agent id, address, and effective execution mode.
            operationId: patchRegistration
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/PatchRegistrationRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/RegistrationResponse'
                    description: Registration updated
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request or nothing to update
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Missing or invalid EIP-191 authentication headers
                "402":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Payment required
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Agent profile not found for signer
                "502":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Upstream service unavailable
            security:
                - eip191Address: []
                  eip191Signature: []
                  eip191Timestamp: []
                  x402Payment: []
            summary: Update registration (ToS signature and/or execution mode)
            tags:
                - Registration
        post:
            description: |
                Create agent registration with EIP-191 request signing (same canonical message as other routes),
                an x402 USDC registration fee, and an EIP-712 signature over the current Terms of Service
                in the JSON body. Fetch signing material from GET /v1/terms-of-service (no auth).
                The recovered signer address is the agent wallet identity.
                Agent wallet provisioning is done separately via POST /v1/wallets.

                This endpoint is **create-only**. If an agent profile already exists for the signer, the request fails with 409.
                To **update** ToS signatures or `execution_mode`, use `PATCH /v1/register`.

                Optional `execution_mode` applies only on create (defaults to `guardrailed`).
            operationId: registerAgent
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/RegisterRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/RegistrationResponse'
                    description: Agent registered successfully
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request, wallet mismatch, or invalid ToS signature
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Missing or invalid EIP-191 authentication headers
                "402":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Payment required
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Agent already registered
                "502":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Upstream service unavailable
            security:
                - eip191Address: []
                  eip191Signature: []
                  eip191Timestamp: []
                  x402Payment: []
            summary: Register a new agent
            tags:
                - Registration
    /v1/skills:
        get:
            description: |
                Root Chainlink for Agents SKILL.md for onboarding, auth, discovery, bundled scripts, and
                references. `{BASE_URL}` in the file is substituted at process start. No
                authentication required.
            operationId: getBundledSkillsHubMarkdown
            responses:
                "200":
                    content:
                        text/markdown:
                            schema:
                                type: string
                    description: Chainlink for Agents skill markdown
            security: []
            summary: Chainlink for Agents skill markdown
            tags:
                - Skills
    /v1/skills/bundle:
        get:
            description: |
                Returns a zip of the full root Chainlink for Agents skill directory. No authentication required.
            operationId: getBundledSkillZip
            responses:
                "200":
                    content:
                        application/zip:
                            schema:
                                format: binary
                                type: string
                    description: Zip archive
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AgentSkillNotFound'
                    description: Skill bundle not found
            security: []
            summary: Download Chainlink for Agents skill as zip
            tags:
                - Skills
    /v1/skills/file/{filepath}:
        get:
            description: Path traversal is rejected. No authentication required.
            operationId: getBundledSkillFile
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                type: string
                        application/octet-stream:
                            schema:
                                format: binary
                                type: string
                        text/markdown:
                            schema:
                                type: string
                        text/plain:
                            schema:
                                type: string
                    description: File bytes
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AgentSkillNotFound'
                    description: File not found
            security: []
            summary: Fetch one file from the Chainlink for Agents skill
            tags:
                - Skills
        parameters:
            - description: Path inside the skill directory (forward slashes; may span subdirectories)
              in: path
              name: filepath
              required: true
              schema:
                type: string
    /v1/streams/reports:
        get:
            description: |
                Returns the signed report for a given feed ID at a specific timestamp.
                Requires EIP-191 agent authentication.
            operationId: getStreamReport
            parameters:
                - description: 0x-prefixed hex-encoded feed ID (32 bytes)
                  in: query
                  name: feedID
                  required: true
                  schema:
                    type: string
                - description: Unix timestamp (seconds)
                  in: query
                  name: timestamp
                  required: true
                  schema:
                    format: uint64
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    report:
                                        $ref: '#/components/schemas/StreamsReportResponse'
                                type: object
                    description: Report at timestamp
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid parameters
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Feed not found
                "502":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Data Streams upstream unavailable
            security:
                - eip191Address: []
                  eip191Signature: []
                  eip191Timestamp: []
                  x402Payment: []
            summary: Get Data Streams report at timestamp
            tags:
                - Streams
    /v1/streams/reports/bulk:
        get:
            description: |
                Returns signed reports for multiple feed IDs at a specific timestamp.
                Maximum 100 feed IDs per request.
                Requires EIP-191 agent authentication.
            operationId: getBulkStreamReports
            parameters:
                - description: Comma-separated 0x-prefixed hex-encoded feed IDs (max 100)
                  in: query
                  name: feedIDs
                  required: true
                  schema:
                    type: string
                - description: Unix timestamp (seconds)
                  in: query
                  name: timestamp
                  required: true
                  schema:
                    format: uint64
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    reports:
                                        items:
                                            $ref: '#/components/schemas/StreamsReportResponse'
                                        type: array
                                type: object
                    description: Reports for requested feeds
                "206":
                    content:
                        application/json:
                            schema:
                                properties:
                                    reports:
                                        items:
                                            $ref: '#/components/schemas/StreamsReportResponse'
                                        type: array
                                type: object
                    description: Partial data — some feeds returned no data
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid parameters
                "502":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Data Streams upstream unavailable
            security:
                - eip191Address: []
                  eip191Signature: []
                  eip191Timestamp: []
                  x402Payment: []
            summary: Get bulk Data Streams reports
            tags:
                - Streams
    /v1/streams/reports/latest:
        get:
            description: |
                Returns the most recent signed report for a given feed ID.
                Requires EIP-191 agent authentication.
            operationId: getLatestStreamReport
            parameters:
                - description: 0x-prefixed hex-encoded feed ID (32 bytes)
                  example: 0x00036f6a26474b3a0da04ae642640db0e30e856e0c19a0a23a80ecc75fa55e12
                  in: query
                  name: feedID
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    report:
                                        $ref: '#/components/schemas/StreamsReportResponse'
                                type: object
                    description: Latest report
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid feed ID format
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Feed not found
                "502":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Data Streams upstream unavailable
            security:
                - eip191Address: []
                  eip191Signature: []
                  eip191Timestamp: []
                  x402Payment: []
            summary: Get latest Data Streams report
            tags:
                - Streams
    /v1/terms-of-service:
        get:
            description: |
                Returns the active ToS version metadata from the gateway database and a ready-to-sign
                EIP-712 `typed_data` object (primary type `ToSAgreement`) matching what registration verifies.
                Use this to build `tos_signature` for `POST /v1/register` (first-time onboarding) or `PATCH /v1/register` (ToS updates). No authentication required.
            operationId: getTermsOfService
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TermsOfServiceResponse'
                    description: Current ToS and EIP-712 typed data
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: ToS metadata unavailable
            summary: Current Terms of Service signing payload
            tags:
                - Discovery
    /v1/wallets:
        get:
            description: |
                Returns wallet records stored for the authenticated agent.
            operationId: listWallets
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListWalletsResponse'
                    description: Wallet list
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "403":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Agent identity missing or ToS required
            security:
                - eip191Address: []
                  eip191Signature: []
                  eip191Timestamp: []
            summary: List registered agent wallets
            tags:
                - Wallets
        post:
            description: |
                Provision a wallet for the authenticated agent. Each agent can have one wallet
                per chain. Requires a valid ToS signature.
            operationId: createWallet
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateWalletRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CreateWalletResponse'
                    description: Wallet created successfully
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request (e.g. missing or unsupported chain_selector)
                "403":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: ToS signature required or agent not registered
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Agent already has a wallet on the requested chain
                "502":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Upstream service unavailable
            security:
                - eip191Address: []
                  eip191Signature: []
                  eip191Timestamp: []
                  x402Payment: []
            summary: Create an agent wallet
            tags:
                - Wallets
servers:
    - description: Chainlink for Agents base URL
      url: https://agents.chain.link
tags:
    - description: Unauthenticated endpoints for agent capability discovery
      name: Discovery
    - description: Agent self-registration with x402 payment and EIP-712 ToS signature
      name: Registration
    - description: Agent wallet provisioning (separate from registration)
      name: Wallets
    - description: On-chain operation submission and tracking
      name: Operations
    - description: Root Chainlink for Agents skill markdown and bundled files at GET /v1/skills, /v1/skills/bundle, /v1/skills/file/*
      name: Skills
    - description: |
        Chainlink Data Streams REST proxy. Returns signed report data for
        specified feed IDs. Requires EIP-191 agent authentication (and ToS guard).
      name: Streams
