openapi.yaml

openapi: 3.1.0
info:
  title: OutLayer API
  version: 0.1.0-alpha.4
  summary: HTTP API for OutLayer custody wallets and policy enforcement
  description: |
    OutLayer Agent Custody — multi-chain wallets for AI agents with TEE-enforced
    policy, multisig approvals, audit log, gasless cross-chain transfers via
    NEAR Intents, and off-chain EVM signing (EIP-712 typed data, EIP-191
    personal_sign, and client-serialized raw transactions).

    Private keys live exclusively inside an Intel TDX TEE and are derived from
    NEAR MPC. The wallet owner sets policy (spending limits, whitelists,
    multisig, freeze) — all enforced inside the TEE before signing.

    See [CUSTODY docs](https://outlayer.ai/docs/agent-custody) for the
    architectural overview and [@outlayer/sdk](https://www.npmjs.com/package/@outlayer/sdk)
    for the TypeScript client.
  license:
    name: MIT
    identifier: MIT
  contact:
    name: OutLayer
    url: https://outlayer.ai

servers:
  - url: https://api.outlayer.ai
    description: Mainnet
  - url: https://testnet-api.outlayer.ai
    description: Testnet — the same API, against NEAR testnet. Pick this one to try a
      call without spending anything real; a mainnet key does not work here, and a
      testnet key does not work on mainnet.

security:
  - BearerAuth: []

tags:
  - name: Registration
    description: Create a new wallet and obtain an API key.
  - name: Execution
    description: >-
      Run a project. A connector is an ordinary project we curated and priced,
      reached through the same route; what being one adds — an `operation` it
      must name, a price it must pay, an owner's secret it may ask for — is
      decided from the project id, not from the way in. Synchronous by default;
      send `async` and poll for anything longer than a few seconds.
  - name: Connectors
    description: >-
      The curated connectors: named, priced operations that reach an outside
      service — a mailbox, a bank, a trading venue — from inside the same
      enclave that holds the caller's keys, so a credential is used without ever
      being handed over. A connector is an ordinary project under
      `connectors.outlayer.near` (`connectors.outlayer.testnet` on testnet) and
      is called through `POST /call/{owner}/{project}` like any other; what
      being curated adds is a price per `operation` on chain and the right to
      read a secret its owner stored for it. A caller who pays is never limited
      by a count of calls — money bounds a funded key, an allowance bounds a
      subscriber — and the one count there is belongs to the trial: fifty calls, in
      a wallet's first week (`POST /trial-key`; the answer's `calls` is the number).


      Which ones exist here, and the skill describing each, come from
      `GET /public/connectors`. What one SELLS is not listed in this spec: its
      operations and their prices are on chain, and the connector's own free
      `status` operation answers with them, as does a refusal — which names what
      could have been asked for instead.


      Every connector publishes an agent-facing skill at
      `https://skills.outlayer.ai/<id>-connector/SKILL.md`, and how to call any
      of them — which key pays, how to be granted an owner's credential — is in
      `https://skills.outlayer.ai/outlayer-connectors/SKILL.md`.
  - name: Subscriptions
    description: >-
      Payment keys, the allowance a subscription buys, and the secret an owner
      leaves for their agent. Only money pays a connector's author: a call
      covered by an allowance costs the caller nothing at the moment of the
      call, so nothing passes through.
  - name: Wallet
    description: >-
      Multi-chain custody operations — transfer, withdraw, swap, balance, and
      signing, including NEAR (NEP-413) message signing and off-chain EVM
      signing (EIP-712 typed data, EIP-191 personal_sign, and client-serialized
      raw transactions).
  - name: Confidential
    description: >-
      Confidential intents — move balances between the public intents shard, the
      Defuse confidential shard, and external chains. The confidential balance
      ledger is real on-chain state on a separate **private** shard (the
      `intents.far` contract, distinct from public `intents.near`); it has no
      public RPC, so you cannot read it externally, but it is an auditable smart
      contract. Only SHIELD/UNSHIELD touch the public chain. Requires
      `ENABLE_CONFIDENTIAL_INTENTS` + the confidential partner agreement on the
      deployment, else every route returns 503. Every operation signs 1Click's
      own intent only as the transfer its quote is (this wallet, the quote's
      deposit address, the quoted asset and amount, nothing else); any other
      message is refused `400 bad_request` before anything is signed. See the
      agent integration guide referenced under `externalDocs` for the full
      mental model, privacy recipes, and curl walkthroughs.
    externalDocs:
      description: >-
        Confidential intents — agent integration guide (mental model, privacy
        recipes, curl walkthroughs)
      url: https://github.com/out-layer/coordinator/blob/main/docs/CONFIDENTIAL_INTENTS.md
  - name: Policy
    description: Encrypted on-chain policy lifecycle (read, encrypt, sign, cache).
  - name: Approvals
    description: Multisig approval workflows for actions that exceed policy thresholds.
  - name: Inbox
    description: >-
      Tasks between an agent and its owner. An agent's run of a project,
      admitted to an owner's secret row by name, leaves that owner a task —
      "confirm this email", "give me your photo"; the owner reads it here,
      inside a session and with no run, and acts on it with a call of their own
      to the operation the task names (`POST /call/{owner}/{project}`, with
      `task_id` and `task_hash`). Reading, rejecting, deleting and muting need
      the session and nothing else.


      What a task shows is ciphertext to this API: `content` is under the
      task's content key, and `device_copy` is that key encrypted to the
      public key of the device the session was opened on. A page opens them
      with the device's private key, which it holds and cannot export
      (ECDH on P-256, HKDF-SHA256, AES-256-GCM). The hash the owner's answer
      names is the SHA-256 of the bytes that were opened.


      Every refusal is an `InboxRefusal`. "Nothing waits" is `{"tasks": []}`,
      never a refusal, and a refusal is never an empty list.
  - name: Audit
    description: Event history for the wallet.
  - name: Requests
    description: Async operation status tracking.
  - name: Meta
    description: Token catalog and helpers.

paths:
  # ============================================================================
  # Registration
  # ============================================================================
  /register:
    post:
      tags: [Registration]
      operationId: registerWallet
      summary: Register a new wallet
      description: |
        Creates a new multi-chain wallet and returns an API key. For most
        callers, send `{}` — an anonymous wallet is created and an API key is
        returned in `api_key` (shown once, not retrievable later).

        Optional fields enable advanced registration paths:
        - `account_id` + `pubkey` + `message` + `signature`: bind the wallet to
          a NEAR account via proof-of-ownership. `pubkey` must be a full-access
          key of `account_id` (or the key of an implicit account not created
          yet); a function-call key is refused. The same holds for every
          `Bearer near:` request and for `PUT /wallet/v1/api-key`.
        - `vault_id`: bind to a customer-owned vault for sovereign custody (see
          vault docs).

        Rate-limited: 30 requests per minute per IP.
      security: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
            examples:
              anonymous:
                summary: Anonymous wallet (most common)
                value: {}
              bound_to_near_account:
                summary: Bind to NEAR account via NEP-413
                value:
                  account_id: alice.near
                  pubkey: ed25519:7BcBZ9Z...
                  message: "register:1716200000"
                  signature: ed25519:5K3F...
      responses:
        '200':
          description: Wallet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterResponse'
              examples:
                anonymous:
                  value:
                    wallet_id: 9c3c9e10-1c1f-4f5e-9c4a-1d7b9a8f3c20
                    api_key: wk_2a8b1f3c4d5e6789abcdef0123456789
                    near_account_id: 9c3c9e101c1f4f5e9c4a1d7b9a8f3c20
                    handoff_url: https://app.outlayer.ai/wallet?key=wk_2a8b...
                    trial:
                      available: true
                      calls: 10
                      days: 7
                      claim_url: POST /trial-key
                      scope: connectors.outlayer.near/*
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  # ============================================================================
  # Wallet — read
  # ============================================================================
  /wallet/v1/address:
    get:
      tags: [Wallet]
      operationId: getAddress
      summary: Derive wallet address for a chain
      description: |
        Returns the deterministically-derived address for the wallet on the
        requested chain. Same `wallet_id` always produces the same addresses
        across chains.

        For `chain=near` the response also carries the two Agent Connect
        identities: `executor_account_id` (always equal to `address` — the
        wallet's implicit account, which signs and pays gas) and
        `asset_account_id` (the bound named account, `null` when the wallet
        has no binding). They are separate fields on purpose: product balances
        belong to the asset account, while signing, predecessor checks and gas
        key off the executor.
      parameters:
        - name: chain
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/Chain'
        - name: sub_path
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/SubPath'
      responses:
        '200':
          description: Address derived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressResponse'
              example:
                wallet_id: 9c3c9e10-1c1f-4f5e-9c4a-1d7b9a8f3c20
                chain: near
                address: 9c3c9e101c1f4f5e9c4a1d7b9a8f3c20
                public_key: ed25519:7BcBZ9Z...
                vault_id: null
                asset_account_id: agent.tla
                executor_account_id: 9c3c9e101c1f4f5e9c4a1d7b9a8f3c20
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/balance:
    get:
      tags: [Wallet]
      operationId: getBalance
      summary: Read balance
      description: |
        Returns the balance for a token on the requested chain. Currently only
        `chain=near` is supported for native balance reads; cross-chain balances
        should be read from the upstream chain directly.

        Set `source=intents` to read the wallet's intents.near balance
        (`mt_balance_of`) instead of the on-chain account balance.

        By default this endpoint answers for the WALLET'S OWN account (the
        executor), bound or not — its meaning never changes when a binding is
        added. Pass `account=asset` to ask about the bound account instead;
        that path is identical to `GET /wallet/v1/binding/balance`, which
        remains available.

        The default is deliberately NOT the binding. Following it would change,
        with no warning, which account an existing caller's number describes —
        including for `personal_account` bindings, whose owners never asked for
        Agent Connect semantics. `asset` is explicit.

        The rule for both sides of the API is one sentence: everything under
        `/wallet/v1/binding/` is the bound account, everything else is the
        wallet itself unless `account=asset` says otherwise.
        `/wallet/v1/transfer` moves the wallet's own funds;
        `/wallet/v1/binding/transfer` moves the bound account's.

        `account=asset` on a wallet with no ACTIVE binding is refused rather
        than answered with the executor's figure under an asset label.

        `source=intents` belongs to the executor and only the executor: an
        intents.near deposit is credited to whoever signed it, so the bound
        account has no intents balance and never will. Combining it with
        `account=asset` is refused.

        The response names the identity it describes in `account`.
      parameters:
        - name: account
          in: query
          required: false
          description: >-
            Which of a bound wallet's two identities the balances describe.
            Omitted means `executor`, unchanged from before this parameter
            existed. `asset` requires an ACTIVE binding and is refused
            otherwise.
          schema:
            type: string
            enum: [asset, executor]
            default: executor
        - name: chain
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Chain'
            default: near
        - name: token
          in: query
          required: false
          schema:
            type: string
          description: Token ID (`nep141:<contract>` or `native`).
        - name: source
          in: query
          required: false
          schema:
            type: string
            enum: [chain, intents]
            default: chain
      responses:
        '200':
          description: Balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
              example:
                balance: '1000000000000000000000000'
                token: NEAR
                account_id: 9c3c9e101c1f4f5e9c4a1d7b9a8f3c20
                account: executor
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/tokens:
    get:
      tags: [Meta]
      operationId: listTokens
      summary: List supported tokens
      description: |
        Returns the token catalog supported for swaps and cross-chain withdraws
        via NEAR Intents. Token IDs are typed as `nep141:<contract>` and map to
        each chain via `defuse_asset_id`.
      responses:
        '200':
          description: Token list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokensResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  # ============================================================================
  # Agent Connect binding (custody wallet ↔ named asset account)
  # ============================================================================
  /wallet/v1/binding:
    put:
      tags: [Wallet]
      operationId: putBinding
      summary: Register the account this wallet operates
      description: |
        Records the one-to-one binding between this custody wallet and an
        on-chain account, in one of two mutually exclusive modes (`kind`):

        * `hos_lease` (default) — a leased, keyless asset account
          (e.g. `agent.tla`). `impl_version` is REQUIRED and gated against
          the supported registry; `owner_account_id` is required.
        * `personal_account` — the caller's own named account
          (e.g. `user.near`) with the upstream no-sign wallet contract the
          owner installs personally (see `GET /wallet/v1/binding/setup`).
          `impl_version` is REJECTED — this mode is versioned by the
          account's wasm code hash, which the client never declares.
          `owner_account_id` is optional and must equal `asset_account_id`.

        The response returns `executor_account_id` — the identity to register
        in the account's extension set (and, for `hos_lease`, to provision a
        spend grant for).

        Guarantees: binding is one-to-one, and a second call naming a
        DIFFERENT asset account is rejected rather than silently rebinding
        (re-PUTting the same pair in the same mode is idempotent). An
        unsupported `impl_version` is rejected here, at binding time, not at
        first execution — that refusal is terminal, do not retry.

        The binding itself authorizes nothing: `binding_status` stays `pending`
        until the executor is first observed live in the extension set on
        chain, and nothing can be executed against the account until its owner
        (for `hos_lease`, the partner's provisioning) puts the executor there.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutBindingRequest'
      responses:
        '200':
          description: Binding recorded (or the identical existing binding)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BindingResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: The wallet or the asset account is already bound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      tags: [Wallet]
      operationId: getBinding
      summary: Read the wallet's binding
      description: |
        Returns the binding record, refreshed against the chain
        (`hos_agent_status` + `nft_item_info`), or 404 when the wallet has
        none. `binding_status` reflects OutLayer's view only — it does not
        attest that the executor is still in the control set, which can change
        without OutLayer being told. `gas_balance` is the executor's native
        NEAR in yoctoNEAR, so it can be topped up before a call fails rather
        than after.
      responses:
        '200':
          description: The binding record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BindingResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: The wallet has no binding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags: [Wallet]
      operationId: deleteBinding
      summary: End the binding
      description: |
        Ends the binding (revocation, transfer, sale, recovery, lease expiry).
        Idempotent — deleting a wallet with no binding is a success. Pending
        multisig approvals whose operation targets the asset account are
        cancelled rather than left completable; the wallet itself survives,
        only the binding ends.
      responses:
        '200':
          description: The binding is ended (or there was none)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteBindingResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/binding/events:
    post:
      tags: [Wallet]
      operationId: postBindingEvent
      summary: Notify OutLayer that a bound account changed
      description: |
        For the account provider (House of Stake) to call on revoke, transfer,
        recovery, freeze or lease change. Authorized by a shared secret in
        `X-Binding-Webhook-Secret`; answers `503` where no secret is
        configured.

        **The body is a hint, not an instruction.** A `revoked` event revokes
        nothing: OutLayer drops its cached view of the account and re-reads the
        chain, and the chain decides the resulting `binding_status`. A webhook
        is an assertion about somebody else's account, so a leaked or
        misconfigured secret must not become the ability to disable an agent by
        name.

        The endpoint is therefore an accelerator with no authority, and it is
        optional: without it, a change is noticed within seconds anyway,
        because every signing pre-flight reads the chain. Skipping it costs
        latency, never correctness.

        Answers `200` with `binding_status: unbound` for an account OutLayer
        does not operate, so an unknown account does not accumulate in a retry
        queue.
      security: []
      parameters:
        - name: X-Binding-Webhook-Secret
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [asset_account_id]
              properties:
                asset_account_id:
                  type: string
                  description: The account the news is about.
                event:
                  type: string
                  description: >-
                    What happened, in the sender's words (`revoked`,
                    `transferred`, `recovered`, `frozen`, …). Logged for
                    correlation; never acted on.
            example:
              asset_account_id: agent.tla
              event: revoked
      responses:
        '200':
          description: Re-read; the status the chain now implies
          content:
            application/json:
              schema:
                type: object
                required: [binding_status]
                properties:
                  binding_status:
                    type: string
                    enum: [pending, active, suspended, revoked, unbound]
        '400':
          description: >-
            The secret was accepted and the body could not be read as an
            event. Deliberately not `422`: in this API that code means the
            chain answered and a receipt failed (`OnChainTxFailed`), and a
            client routing on it must not meet it here.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          description: No binding-event secret is configured on this deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    get:
      tags: [Wallet]
      operationId: getBindingZones
      summary: Which account names this webhook may report on
      description: |
        The account-name suffixes `POST /wallet/v1/binding/events` accepts,
        read with the same `X-Binding-Webhook-Secret`. Ask before sending the
        first event for a newly opened zone: an account outside the list
        answers `binding_status: unbound` and nothing happens.

        An EMPTY list means no zone restriction — every name is accepted,
        subject to the rule that always applies (only leased bindings are
        reachable at all). Zones are editable by OutLayer without a restart, so
        a new one takes effect as soon as it is added.
      security: []
      parameters:
        - name: X-Binding-Webhook-Secret
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The zones currently accepted
          content:
            application/json:
              schema:
                type: object
                required: [zones]
                properties:
                  zones:
                    type: array
                    items:
                      type: string
              example:
                zones: [tla.near]
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          description: No binding-event secret is configured on this deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /wallet/v1/binding/balance:
    get:
      tags: [Wallet]
      operationId: getBindingBalance
      summary: Read the BOUND account's balance
      description: |
        The balance of the account this wallet is bound to — where an Agent
        Connect wallet's product money lives. The wallet's own account (gas,
        and anything it holds itself) is `GET /wallet/v1/balance`.

        Requires an ACTIVE binding. A `pending` one answers 400 saying so: it
        authorizes nothing, and the executor is not in the account's extension
        set yet, so the account holds nothing on this wallet's behalf. No
        binding at all answers 404. Neither ever falls back to the wallet's own
        figure under an asset label — a number the owner acts on must not
        quietly be about a different account.

        `source=intents` is refused here and pointed at `/wallet/v1/balance`:
        intents deposits are credited to the signer, which is always the
        executor.
      parameters:
        - name: token
          in: query
          required: false
          schema:
            type: string
          description: Token ID (`nep141:<contract>` or `native`).
      responses:
        '200':
          description: Balance of the bound account (`account` is `asset`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: The wallet has no binding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/binding/transfer:
    post:
      tags: [Wallet]
      operationId: bindingTransfer
      summary: Spend from the BOUND account
      description: |
        Move native NEAR or a NEP-141 token out of the bound asset account.

        A BUILDER over the existing lane, not a new one. What gets signed is
        exactly the `w_execute_extension` you could post to `/wallet/v1/call`
        yourself: same canonical op, same pre-flight, same spend-grant rules,
        same policy evaluation, same multisig trigger, same per-promise receipt
        handling. It exists so you do not have to assemble a nested base64
        envelope by hand.

        Separate from `/wallet/v1/transfer` because it is a different
        operation, not a mode of the same one: `/wallet/v1/transfer` signs a
        plain transfer from the wallet's own account, this signs a contract
        call under an on-chain grant, with its own error classes
        (`agent_connect_denied`) and its own approval path.

        Responses are those of `/wallet/v1/call`, including `403
        agent_connect_denied` when the pre-flight refuses — read `terminal`
        before retrying.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [to, amount]
              properties:
                to:
                  type: string
                  description: >-
                    Where the value lands. For a token this is the LOGICAL
                    recipient, not the token contract.
                amount:
                  type: string
                  description: >-
                    Native yoctoNEAR, or the token's own smallest unit when
                    `token` is set.
                token:
                  type: [string, 'null']
                  description: NEP-141 contract. Absent means native NEAR.
                memo:
                  type: [string, 'null']
                  description: NEP-141 `memo`, passed through untouched.
      responses:
        '200':
          description: Accepted; same shape as `/wallet/v1/call`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The Agent Connect pre-flight refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConnectDeniedResponse'
        '404':
          description: The wallet has no binding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Another operation holds this wallet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/binding/setup:
    get:
      tags: [Wallet]
      operationId: getBindingSetup
      summary: Installation kit for a personal_account binding
      description: |
        `kind=personal_account` only (for `hos_lease` the partner provisions
        accounts, and this endpoint answers 400). Requires an existing
        `personal_account` binding for the wallet.

        Returns ONE transaction of three actions — reference the wallet code
        by its global-contract hash, `w_init` (1 yoctoNEAR), and
        `w_execute_extension` adding the executor as an extension — with
        receiver = signer = the owner's own account. OutLayer only assembles
        payloads; the owner signs with any wallet, and their signature is
        what authorizes the lane, once and entirely.

        HARD refusal, not a warning: if the account already has ANY contract
        deployed, the kit answers 409 — deploying over it would not clear the
        old contract's state (the typical victim being a 2FA/multisig wallet
        contract).

        The wallet code is referenced by GLOBAL-CONTRACT HASH, and a global
        contract is published per network: the same wasm has the same hash
        everywhere, but somebody has to publish it once on each chain. This
        endpoint checks that before handing you a transaction, and answers 400
        where it has not been published — otherwise you would sign a
        transaction that cannot succeed.
      parameters:
        - name: kind
          in: query
          required: true
          schema:
            type: string
            enum: [personal_account]
      responses:
        '200':
          description: The installation transaction, ready to sign
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BindingSetupResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: The wallet has no binding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The account already has a contract deployed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          description: |
            The chain could not be read just now, so neither the account's
            current code nor the availability of the wallet contract could be
            confirmed. Transient — retry. (A network where the wallet contract
            is not published answers 400 instead, because that does not change
            on a retry.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # ============================================================================
  # Wallet — write
  # ============================================================================
  /wallet/v1/call:
    post:
      tags: [Wallet]
      operationId: call
      summary: Sign and broadcast a NEAR function call
      description: |
        Native NEAR contract call. Policy is enforced before signing; if the
        call exceeds limits, the response carries `status=pending_approval`
        and an `approval_id` for the multisig flow.

        `call` gives the agent what the wallet's own NEAR account can do:
        an `ft_transfer` moves that token whatever the per-token limits say
        (they see the 1 yoctoNEAR deposit). A call to the NEAR Intents contract
        (`intents.near`) is refused (`403 policy_denied`) unless the policy sets
        `capabilities.intents_call` — see `Capabilities`; use the
        `/wallet/v1/intents/*` endpoints instead.


        Agent Connect: a `w_execute_extension` call aimed at the wallet's own
        bound account is additionally checked against the LIVE chain — binding
        liveness, spend grant, call form, reserve floor — before anything is
        signed. That refusal is a `403` shaped as `AgentConnectDeniedResponse`
        (not the generic error body), carrying the class, the promise index and
        a `terminal` flag. The policy engine independently decodes the same
        request and rules it on the owner's own limits.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallRequest'
            example:
              receiver_id: usdt.tether-token.near
              method_name: ft_transfer
              args:
                receiver_id: bob.near
                amount: '1000000'
              gas: '30000000000000'
              deposit: '1'
      responses:
        '200':
          description: Call submitted (or queued for approval)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            Refused by policy, or — for `w_execute_extension` on a bound
            account — by the Agent Connect pre-flight, which answers
            `AgentConnectDeniedResponse`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - $ref: '#/components/schemas/AgentConnectDeniedResponse'
        '409':
          description: >-
            Another money-moving operation is using this wallet. Applies to
            every spending endpoint, not only this one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletBusyResponse'
        '422':
          $ref: '#/components/responses/OnChainTxFailed'
        '429':
          description: >-
            Too many requests from this client (`rate_limited`), or the
            wallet's custody ceiling (`operation_limit_reached`, with the
            ceiling and `Retry-After` — see OperationLimitReachedResponse).
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - $ref: '#/components/schemas/OperationLimitReachedResponse'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          description: >-
            The chain could not be reached to verify a binding. Transient —
            retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /wallet/v1/transfer:
    post:
      tags: [Wallet]
      operationId: transfer
      summary: Native chain transfer
      description: |
        Chain-agnostic native transfer (NEAR yoctoNEAR units). Currently only
        `chain=near` is supported; other chains return `unsupported_chain`.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferRequest'
            example:
              chain: near
              to: bob.near
              amount: '1000000000000000000000000'
      responses:
        '200':
          description: Transfer submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/OnChainTxFailed'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/delete:
    post:
      tags: [Wallet]
      operationId: deleteWallet
      summary: Delete the wallet account, sweeping its full balance to a beneficiary
      description: |
        Irreversible. Signs and broadcasts NEAR's native `DeleteAccount`
        action, which sends the wallet account's **entire** remaining NEAR
        balance to `beneficiary`, revokes all API keys, and marks the wallet
        deleted. Guards: the beneficiary cannot be the wallet's own account,
        the wallet must have a non-zero on-chain balance (a zero-balance
        implicit account does not exist on-chain), and the wallet must not be
        already deleted. Policy is enforced before signing; on a multisig
        wallet the response carries `status=pending_approval` and an
        `approval_id` for the multisig flow.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteRequest'
            example:
              beneficiary: treasury.near
              chain: near
      responses:
        '200':
          description: Account deleted (or queued for approval)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/OnChainTxFailed'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/storage-deposit:
    post:
      tags: [Wallet]
      operationId: storageDeposit
      summary: Register storage on a NEP-141 token contract
      description: |
        Calls `storage_deposit` (with `registration_only: true`) on a NEP-141
        token contract so `account_id` (defaults to the wallet's own NEAR
        address) can hold that token. Idempotent: if the account is already
        registered the call returns `already_registered: true` without signing
        a transaction. The wallet must have NEAR to pay gas when a transaction
        is required. Policy gates this as a `call`; multisig is not supported
        for this endpoint.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StorageDepositRequest'
            example:
              token: wrap.near
      responses:
        '200':
          description: Storage registered (or already registered)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageDepositResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/OnChainTxFailed'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/intents/deposit:
    post:
      tags: [Wallet]
      operationId: intentsDeposit
      summary: Deposit FT into intents.near
      description: |
        Wraps `ft_transfer_call` to `intents.near`, auto-handling storage
        deposit if required. After this call, the wallet's intents.near balance
        increases by `amount` of `token` and is available for swaps and
        gasless cross-chain withdrawals.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntentsDepositRequest'
            example:
              token: wrap.near
              amount: '5000000000000000000000000'
      responses:
        '200':
          description: Deposit submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntentsDepositResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/OnChainTxFailed'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/intents/withdraw:
    post:
      tags: [Wallet]
      operationId: intentsWithdraw
      summary: Withdraw via NEAR Intents (native NEAR / wNEAR / cross-chain)
      description: |
        Gasless withdrawal through NEAR Intents solver relay. The wallet's
        intents.near balance is debited; the receiver gets funds without paying
        gas on either side.

        **`chain=near`** — the `token` field selects what the recipient receives:
          - omitted / `near` / `native` (default): **native NEAR**. intents.near
            unwraps the wallet's wNEAR (`native_withdraw` intent) and sends native
            NEAR. The recipient needs **no** `wrap.near` storage. The recipient
            account must already exist (or be a 64-char implicit account) —
            withdrawing to a non-existent named account is rejected (the unwrapped
            wNEAR would otherwise be burned).
          - `nep141:wrap.near`: **wNEAR** (NEP-141). Recipient must be
            storage-registered on `wrap.near`.
          - other `nep141:<token>`: that NEP-141. Recipient must be storage-registered.

        **Other chains** (`ethereum`, `solana`, `bitcoin`, ...) — `token` is the
        source Intents asset; 1Click bridges and delivers the destination chain's
        native asset.

        If the policy requires approval, returns `status=pending_approval` with
        an `approval_id`.

        **Cross-chain withdrawals are best called with `async=true`**: the bridge
        can take longer than the synchronous response window, so the call returns
        `status=processing` + a `poll_url` immediately and you poll
        `GET /wallet/v1/requests/{request_id}` for the terminal status.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/AnswerWithin'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawRequest'
            examples:
              nativeNear:
                summary: Native NEAR (default for chain=near)
                value:
                  chain: near
                  to: receiver.near
                  amount: '1000000000000000000000000'
                  token: near
              wnear:
                summary: wNEAR (NEP-141, recipient needs wrap.near storage)
                value:
                  chain: near
                  to: receiver.near
                  amount: '1000000000000000000000000'
                  token: nep141:wrap.near
              crossChain:
                summary: Cross-chain (1Click delivers native on the target chain)
                value:
                  chain: ethereum
                  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f8b4f5'
                  amount: '1000000'
                  token: nep141:usdt.tether-token.near
      responses:
        '200':
          description: Withdraw submitted (or queued for approval)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/RouteUnavailable'

  /wallet/v1/intents/withdraw/dry-run:
    post:
      tags: [Wallet]
      operationId: intentsWithdrawDryRun
      summary: Simulate a withdraw (policy + balance check, no execution)
      description: |
        Runs the full policy and balance check for a withdraw without signing
        or broadcasting. Useful for showing the user whether an action would
        succeed before they confirm.

        Every pre-condition the real withdraw enforces is evaluated here, in the
        same order: request shape, policy (same canonical op — cross-chain is
        gated by the separate `cross_chain_withdraw` capability), intents
        balance, NEAR recipient existence / NEP-141 storage registration, and —
        for a cross-chain withdraw — a `dry` 1Click quote. The quote is what
        surfaces bridge minimums, unsupported routes and missing liquidity
        before the user confirms; its result is summarised in `message`.

        Approval-gated wallets get the same pre-condition checks: a
        `would_succeed: true` with `message` "Operation would require multisig
        approval" means the op is executable once approvers sign.

        Cross-chain results omit `estimated_fee`/`fee_token` — the bridge takes
        its cut out of the transferred amount rather than charging NEAR gas, so
        the quote line in `message` is the cost estimate.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawRequest'
      responses:
        '200':
          description: Dry-run result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DryRunResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/RouteUnavailable'

  /wallet/v1/intents/storage-deposit:
    post:
      tags: [Wallet]
      operationId: intentsStorageDeposit
      summary: Register storage on a NEP-141 token, paid from the intents wNEAR balance
      description: |
        Registers `account_id` (defaults to the wallet's own NEAR account) on the
        NEP-141 contract `token`, paid with the wallet's **wNEAR inside
        `intents.near`** — the defuse `storage_deposit` intent, gasless via the
        solver relay. The wallet needs no native NEAR. `POST
        /wallet/v1/storage-deposit` does the same paid in native NEAR from the
        wallet's on-chain account.

        The usual use: before `POST /wallet/v1/intents/withdraw` of a NEP-141 to
        an account with no storage on the token (the withdraw answers
        `storage_not_registered`), register that account here and retry.

        The amount is the token contract's `storage_balance_bounds().min`, read
        at the call, and at most 0.00125 NEAR (`1250000000000000000000`
        yoctoNEAR, the minimum of a standard NEP-141): a token asking more is
        `400`, register it through `POST /wallet/v1/call`. `intents.near` never
        refunds the wNEAR it spends on a storage deposit, so nothing is signed
        for an account that is already registered: the answer is `success` with
        `already_registered: true`, before the policy and any approval. A
        registration that cannot be read is a `503`, never treated as absent.
        While a deposit for the same token and account is `processing` or
        `pending_approval` on this wallet, another is `409 conflict` naming
        that request.

        `success` means the account IS registered: the deposit runs after the
        intent in a separate receipt, and the call answers `processing` with a
        `poll_url` until `storage_balance_of` shows it. A request whose intent
        executed and left the account unregistered ends `failed` with
        `result.wnear_spent: true`.

        Gated by the policy as its own type, `intents_storage_deposit`: it
        spends the intents balance, so neither `call` nor `storage_deposit`
        permits it. The token contract is the destination for an address list,
        the wNEAR (`nep141:wrap.near`) the token for limits. On a wallet that requires approval it answers
        `pending_approval`. A wNEAR balance below the deposit is `400
        insufficient_balance`. NEAR Intents is mainnet-only: `503` on testnet.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/AnswerWithin'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntentsStorageDepositRequest'
            examples:
              receiver:
                summary: Register a withdraw receiver on USDC
                value:
                  token: 17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1
                  account_id: 4f2d8a1c9b3e7f60a5d4c3b2a1908f7e6d5c4b3a29180f7e6d5c4b3a29180f7e
      responses:
        '200':
          description: Registered, already registered, processing, or queued for approval
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntentsStorageDepositResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: A deposit for the same token and account is already under way; the message names its request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/intents/transfer:
    post:
      tags: [Wallet]
      operationId: intentsTransfer
      summary: Transfer inside NEAR Intents (to another account's intents balance)
      description: |
        Move a token balance from the wallet's `intents.near` balance to **another
        account's** `intents.near` balance, staying **inside** the intents pool
        (the defuse `transfer` intent). Gasless via the solver relay — neither side
        pays NEAR gas.

        This is **not** a withdrawal: funds never leave `intents.near`. Use
        `POST /wallet/v1/intents/withdraw` to deliver to a plain on-chain account
        instead. NEAR-only: there is no `chain` field, and `token` is **required**
        (to send NEAR, transfer `nep141:wrap.near`).

        The recipient is credited inside `intents.near`, so the account need **not**
        exist on-chain (a 64-hex implicit OutLayer wallet is a valid recipient); only
        the account-id format is validated.

        Gated by the wallet policy exactly like withdraw (recipient whitelist +
        per-token amount limit). If the policy requires approval, returns
        `status=pending_approval` with an `approval_id`.

        Answers once the transfer settles. When the solver relay outlasts the
        call's wait it answers `status=processing` with a `poll_url`, and the
        transfer settles on its own; it runs to its outcome even if the caller
        disconnects.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/AnswerWithin'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntentsTransferRequest'
            examples:
              usdt:
                summary: Transfer USDT to another account's intents balance
                value:
                  to: partner.near
                  amount: '1000000'
                  token: nep141:usdt.tether-token.near
      responses:
        '200':
          description: Transfer submitted (or queued for approval)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/intents/swap:
    post:
      tags: [Wallet]
      operationId: intentsSwap
      summary: Swap via NEAR Intents (1Click)
      description: |
        Cross-chain swap via the 1Click solver. Quote → deposit to intents.near
        → mt_transfer → poll. Returns when the swap settles or fails.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/AnswerWithin'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwapRequest'
            example:
              token_in: nep141:wrap.near
              token_out: nep141:usdt.tether-token.near
              amount_in: '5000000000000000000000000'
              min_amount_out: '24000000'
      responses:
        '200':
          description: Swap submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwapResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/RouteUnavailable'

  /wallet/v1/intents/swap/quote:
    post:
      tags: [Wallet]
      operationId: intentsSwapQuote
      summary: Get a swap quote (no execution)
      description: |
        Returns the indicative output and deadline for a swap without executing
        it. Use this before calling `/intents/swap` to show the user expected
        output and allow them to set `min_amount_out`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwapRequest'
      responses:
        '200':
          description: Quote
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwapQuoteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/RouteUnavailable'

  /wallet/v1/evm/sign-typed-data:
    post:
      tags: [Wallet]
      operationId: evmSignTypedData
      summary: Sign EIP-712 typed data (EVM)
      description: |
        Sign an EIP-712 v4 typed-data object with the wallet's EVM (secp256k1)
        key for `chain`. The digest is computed server-side from the full
        typed-data object (no client-supplied hash is trusted); `ecrecover` over
        it returns the address from `GET /wallet/v1/address?chain=<evm>`. This is
        the core trading primitive (signs CLOB orders). Off-chain — returns the
        signature only, no broadcast. Gated by the `evm_sign` capability.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvmSignTypedDataRequest'
      responses:
        '200':
          description: Signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmSignResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/evm/sign-message:
    post:
      tags: [Wallet]
      operationId: evmSignMessage
      summary: Sign an EIP-191 personal_sign message (EVM)
      description: |
        Sign an EIP-191 `personal_sign` message with the wallet's EVM key.
        `message` is `0x`-hex (signed as raw bytes) or a UTF-8 string. Used for
        venue L1 auth (e.g. deriving a Polymarket CLOB API key). Gated by the
        `evm_sign` capability.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvmSignMessageRequest'
      responses:
        '200':
          description: Signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmSignResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/evm/sign-transaction:
    post:
      tags: [Wallet]
      operationId: evmSignTransaction
      summary: Sign a raw EVM transaction
      description: |
        Sign a raw EVM transaction with the wallet's EVM key. The caller supplies
        the **serialized unsigned transaction** (`unsigned_tx`, e.g. viem
        `serializeTransaction(tx)` — `0x02‖rlp(...)` for EIP-1559); the service
        keccak256-hashes it and returns the recoverable signature. It does NOT
        assemble the transaction, manage nonce/gas, or broadcast — the caller
        assembles the final signed tx and broadcasts it. For an EIP-1559 tx the
        `yParity` needed to assemble is `v - 27`. Gated by the **`evm_sign.raw_tx`**
        sub-capability (default-OFF, separate from base `evm_sign`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvmSignTransactionRequest'
      responses:
        '200':
          description: Signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmSignResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/solana/sign-message:
    post:
      tags: [Wallet]
      operationId: solanaSignMessage
      summary: Sign an off-chain message (Solana)
      description: |
        Sign raw message bytes with the wallet's Solana (ed25519) key. The
        decoded bytes are signed AS-IS (Solana convention — verifiable with
        `nacl.sign.detached.verify`; Sign-in-with-Solana flows work unchanged).
        Bytes that parse as a valid Solana **transaction message** are rejected
        (HTTP 400): Solana has no EIP-191-style prefix separating messages from
        transactions, so this guard (the same one Phantom/Solflare apply) keeps
        the message endpoint from bypassing the `solana_sign.raw_tx`
        sub-capability. Off-chain — returns the signature only, no broadcast.
        Gated by the `solana_sign` capability. The `sol` alias is accepted for
        `chain` and canonicalized — the response always echoes `solana`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SolanaSignMessageRequest'
      responses:
        '200':
          description: Signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolanaSignResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/solana/sign-transaction:
    post:
      tags: [Wallet]
      operationId: solanaSignTransaction
      summary: Sign a Solana transaction message
      description: |
        Sign a Solana transaction with the wallet's Solana (ed25519) key. The
        caller supplies the **serialized unsigned transaction message**
        (`unsigned_tx`, base64 — what the signature covers: web3.js
        `tx.serializeMessage()` / `versionedTx.message.serialize()`); the
        service signs the bytes as-is and returns the base58 signature. It does
        NOT parse or assemble the transaction, pick a blockhash, or broadcast —
        the caller assembles the signed tx
        (`compact-u16 signature count ‖ signatures ‖ message`) and broadcasts
        it. Gated by the **`solana_sign.raw_tx`** sub-capability (default-OFF,
        separate from base `solana_sign`). The `sol` alias is accepted for
        `chain` and canonicalized — the response always echoes `solana`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SolanaSignTransactionRequest'
      responses:
        '200':
          description: Signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolanaSignResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  # ============================================================================
  # Confidential intents (Defuse confidential shard)
  # ============================================================================
  /wallet/v1/confidential/shield:
    post:
      tags: [Confidential]
      operationId: confidentialShield
      summary: SHIELD — move public intents balance into the confidential shard
      description: |
        Moves the wallet's **public** `intents.near` balance into its
        confidential balance (deposit-type `INTENTS` → recipient-type
        `CONFIDENTIAL_INTENTS`).

        **Privacy note:** SHIELD links the wallet to the confidential pool
        **on-chain** (an `execute_intents` call signed by the wallet, with the
        public asset id visible). It is a convenience hop, not an unlinkable
        operation — for unlinkability fund the confidential balance via
        `confidentialDepositCrossChain` (cross-chain) instead. See CUSTODY docs.

        Async: returns `status=pending_deposit` with a `request_id`; poll
        `GET /wallet/v1/requests/{id}` until terminal.

        **Legacy alias:** `POST /wallet/v1/confidential/deposit` still works and
        resolves to the same handler.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfidentialShieldRequest'
            example:
              token: nep141:wrap.near
              amount: '10000000000000000000000'
      responses:
        '200':
          description: Shield submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfidentialOpResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/confidential/deposit:
    post:
      tags: [Confidential]
      operationId: confidentialDeposit
      deprecated: true
      summary: '[Deprecated] SHIELD into the confidential shard (use /wallet/v1/confidential/shield)'
      description: |
        **Deprecated legacy alias.** Use
        [`confidentialShield`](#tag/Confidential/operation/confidentialShield)
        (`POST /wallet/v1/confidential/shield`) instead. Retained for backward
        compatibility; resolves to the same handler with identical
        request/response shapes.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfidentialShieldRequest'
            example:
              token: nep141:wrap.near
              amount: '10000000000000000000000'
      responses:
        '200':
          description: Shield submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfidentialOpResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/confidential/unshield:
    post:
      tags: [Confidential]
      operationId: confidentialUnshield
      summary: UNSHIELD — move confidential balance back to public intents
      description: |
        Reverse of SHIELD (deposit-type `CONFIDENTIAL_INTENTS` → recipient-type
        `INTENTS`). Like SHIELD, this links the wallet on-chain (exit-to-public
        reveal). Async — poll `GET /wallet/v1/requests/{id}`.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfidentialUnshieldRequest'
            example:
              token: nep141:wrap.near
              amount: '10000000000000000000000'
      responses:
        '200':
          description: Unshield submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfidentialOpResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/confidential/withdraw:
    post:
      tags: [Confidential]
      operationId: confidentialWithdraw
      summary: Withdraw a confidential balance to an external chain
      description: |
        Moves a confidential balance out to a destination chain
        (`CONFIDENTIAL_INTENTS` → `DESTINATION_CHAIN`). The wallet's NEAR address
        never appears on chain — only the destination-chain receiver does, on the
        destination chain.

        `chain` is the token's **home chain** (e.g. `chain=zcash` for
        `nep141:zec.omft.near`, delivering the native asset to a
        destination-chain address), `"near"`, or any other supported chain:
        there the SAME symbol on that chain's 1Click listing is delivered,
        swapped on the way — NEAR USDC withdrawn with `chain=hypercore`
        arrives as HyperCore's HIP-1 USDC, with `chain=polygon` as Polygon
        USDC. A token with no listing of its symbol on that chain is refused.

        `chain="near"` delivers to the named NEAR account. For NEAR-native
        tokens (`nep141:wrap.near` → **native NEAR** via a `native_withdraw`
        intent on `intents.near`, verified live: settlement
        `FVzan8XRMwHYPe2hgX4GffwG3bdndxETWb2FKVFzFdur`). For omft bridge
        assets (e.g. `nep141:zec.omft.near`) the NEP-141 representation is
        delivered **on NEAR** (`1cs_v1:near:<asset>` destination) — the funds
        stay bridged instead of being withdrawn to the token's home chain. To
        send funds back to your **own** public intents balance use
        `confidentialUnshield` (different semantics — self vs. external
        recipient).

        `token` is **required** — the source confidential asset to deliver on the
        destination chain. The same per-chain whitelist / spending-limit policy
        as `intentsWithdraw` is enforced. Async — poll
        `GET /wallet/v1/requests/{id}`.

        **Delivery to a NEAR account is a direct NEP-141 `ft_transfer`** to the
        recipient (not an intents-balance credit). The recipient does NOT need
        prior storage registration on the token contract: 1Click checks it and,
        for an unregistered recipient, registers the storage itself, netting
        its cost out of `amount_out` (observable in the dry-run quote — an
        unregistered recipient is quoted slightly less than a registered one).
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfidentialWithdrawRequest'
            example:
              chain: solana
              to: Esf7JS1sM46vEHtk75ik7N7UD5FJ13TXVKGWEd2kksiw
              amount: '500000'
              token: nep141:sol-5ce3bf3a31af18be40ba30f721101b4341690186.omft.near
      responses:
        '200':
          description: Withdraw submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfidentialOpResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/confidential/withdraw/dry-run:
    post:
      tags: [Confidential]
      operationId: confidentialWithdrawDryRun
      summary: Quote a confidential withdraw (no execution)
      description: |
        Returns the indicative output for a confidential withdraw without
        signing or submitting. Read-only.

        Applies the same gates as the real confidential withdraw, in the same
        order: `to` is required (400 without it), then the policy decision over
        the same canonical op (403 when frozen or denied), then the upstream
        quote. A wallet whose policy requires approval still gets its quote —
        the op is executable once approvers sign.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfidentialWithdrawRequest'
      responses:
        '200':
          description: Quote
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwapQuoteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/confidential/transfer:
    post:
      tags: [Confidential]
      operationId: confidentialTransfer
      summary: Private transfer inside the confidential shard
      description: |
        Transfers a confidential balance to another NEAR account, fully inside
        the confidential shard (`CONFIDENTIAL_INTENTS` → `CONFIDENTIAL_INTENTS`).
        Settles on the private shard, so it leaves no public-chain trace.
        NEAR-only context — no `chain` field; `token`
        required. Async — poll `GET /wallet/v1/requests/{id}`.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfidentialTransferRequest'
            example:
              to: '950c134ec86a21a8525d16d1dbae79258b923cabdaa8d32da284d931f74bdcb2'
              amount: '1000000'
              token: nep141:wrap.near
      responses:
        '200':
          description: Transfer submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfidentialOpResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/confidential/swap:
    post:
      tags: [Confidential]
      operationId: confidentialSwap
      summary: Swap between two assets inside the confidential shard
      description: |
        Confidential swap with distinct `token_in`/`token_out`, both settled
        inside the confidential shard. Settles on the private shard, so it leaves
        no public-chain trace. Async — poll
        `GET /wallet/v1/requests/{id}`.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfidentialSwapRequest'
            example:
              token_in: nep141:wrap.near
              token_out: nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1
              amount_in: '5000000000000000000000000'
      responses:
        '200':
          description: Swap submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfidentialOpResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/confidential/swap/quote:
    post:
      tags: [Confidential]
      operationId: confidentialSwapQuote
      summary: Quote a confidential swap (no execution)
      description: Read-only price preview for a confidential swap.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfidentialSwapRequest'
      responses:
        '200':
          description: Quote
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwapQuoteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/confidential/deposit/cross-chain:
    post:
      tags: [Confidential]
      operationId: confidentialDepositCrossChain
      summary: Cross-chain deposit into the confidential shard (quote only)
      description: |
        Requests a one-time deposit address to fund the confidential balance
        from an external chain (`ORIGIN_CHAIN` → `CONFIDENTIAL_INTENTS`) via
        1Click / NEAR Intents. The caller sends `amount` of the source asset to
        the returned `deposit_address` out-of-band; the solver delivers it and
        credits the confidential balance. **The wallet's NEAR address never
        touches the public side** — this is the most private way to fund a
        confidential balance. Poll `GET /wallet/v1/requests/{id}` for status.

        **Refunds.** A failed bridge refunds into the confidential balance,
        except from `hypercore`, whose assets refund only on their origin
        chain. There the address is resolved as on the public route
        ([`DepositIntentRequest`](#/components/schemas/DepositIntentRequest)):
        the wallet policy's `refund_addresses.hypercore`; a policy without one
        → the wallet's derived HyperCore address, and the request's
        `refund_address` is ignored (the `hint` says so); no policy → the
        request's `refund_address` (format-checked), else the derived address.

        **Legacy alias:** `POST /wallet/v1/confidential/deposit-intent` still
        works and resolves to the same handler.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfidentialDepositIntentRequest'
            example:
              source_asset: nep141:sol-5ce3bf3a31af18be40ba30f721101b4341690186.omft.near
              amount: '500000'
      responses:
        '200':
          description: Deposit address issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfidentialDepositIntentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/confidential/deposit-intent:
    post:
      tags: [Confidential]
      operationId: confidentialDepositIntent
      deprecated: true
      summary: '[Deprecated] Cross-chain deposit into the confidential shard (use /wallet/v1/confidential/deposit/cross-chain)'
      description: |
        **Deprecated legacy alias.** Use
        [`confidentialDepositCrossChain`](#tag/Confidential/operation/confidentialDepositCrossChain)
        (`POST /wallet/v1/confidential/deposit/cross-chain`) instead. Retained
        for backward compatibility; resolves to the same handler with identical
        request/response shapes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfidentialDepositIntentRequest'
            example:
              source_asset: nep141:sol-5ce3bf3a31af18be40ba30f721101b4341690186.omft.near
              amount: '500000'
      responses:
        '200':
          description: Deposit address issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfidentialDepositIntentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/confidential/balance:
    get:
      tags: [Confidential]
      operationId: confidentialBalance
      summary: Read confidential balances
      description: |
        Returns the wallet's confidential balances from the private shard
        (`intents.far`), which has no public RPC of its own. With `?token=`
        returns a single asset; without it returns the
        full list. Accepts both `wrap.near` and `nep141:wrap.near` forms.
      parameters:
        - name: token
          in: query
          required: false
          schema:
            type: string
          description: Defuse asset id to filter to (e.g. `nep141:wrap.near`). Omit for all.
      responses:
        '200':
          description: Confidential balance(s)
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ConfidentialBalanceResponse'
                  - $ref: '#/components/schemas/ConfidentialBalancesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/intents/deposit/cross-chain:
    post:
      tags: [Wallet]
      operationId: intentsDepositCrossChain
      summary: Create a cross-chain deposit (via 1Click / NEAR Intents)
      description: |
        Requests a one-time deposit address on a source chain via NEAR Intents
        1Click. The caller sends `amount` of the source token to the returned
        `deposit_address`; the solver delivers it and credits the wallet's
        intents.near balance. Poll `getCrossChainDepositStatus` until `success`.

        This is a **cross-chain deposit via 1Click / NEAR Intents** — the
        wallet's NEAR address receives the intents.near credit once the solver
        settles the source-chain deposit.

        Two request shapes are accepted (see
        [`DepositIntentRequest`](#/components/schemas/DepositIntentRequest)):

        - **By asset id (preferred)** — `{ source_asset, destination_asset?,
          amount }`. The source chain is derived from the
          [`defuse_asset_id`](#/components/schemas/TokenInfo) prefix. This is
          the shape returned by `listTokens` and used by the dashboard.
        - **By chain + symbol (legacy)** — `{ chain, token?, amount }`. The
          coordinator resolves `(chain, symbol)` to an asset id via the
          1Click token catalog.

        If both shapes are present and disagree, `source_asset` wins and the
        coordinator logs a warning. `near` is a valid source chain — a
        NEAR-origin deposit returns a 64-char hex implicit account.

        Amounts are in the token's smallest unit. There's a small solver fee,
        so `amount_out` < `amount`.

        **Refunds.** If the bridge fails, funds return on the source chain.
        Where is the owner's decision: the wallet policy's `refund_addresses`
        entry for that chain; a policy without one → the wallet's derived
        address on the chain when it has one (NEAR, Solana, EVM chains,
        HyperCore), and the request's `refund_address` is ignored (the `hint`
        says so); else → the request's `refund_address`. No policy → the
        request's `refund_address`, else the derived address. A request
        address is format-checked for the chain. A deposit from a chain the
        wallet has no address on (Bitcoin, Zcash, Tron, …) with neither a
        policy entry nor a `refund_address` is refused with `400`.

        The returned `deposit_address` is chain-specific — see the
        [`DepositIntentResponse.deposit_address`](#/components/schemas/DepositIntentResponse)
        description for per-chain address formats.

        **Legacy alias:** `POST /wallet/v1/deposit-intent` still works and
        resolves to the same handler.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DepositIntentRequest'
            examples:
              bySourceAsset:
                summary: USDC on Base → NEAR USDC (preferred shape)
                value:
                  source_asset: nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near
                  destination_asset: nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1
                  amount: '5000000'
              byChainAndToken:
                summary: USDC on Ethereum (legacy shape)
                value:
                  chain: ethereum
                  token: USDC
                  amount: '5000000'
              nearNative:
                summary: NEAR-origin deposit (returns a NEAR implicit account)
                value:
                  source_asset: nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1
                  amount: '5000000'
      responses:
        '200':
          description: Deposit intent created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositIntentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/deposit-intent:
    post:
      tags: [Wallet]
      operationId: createDepositIntent
      deprecated: true
      summary: '[Deprecated] Create a cross-chain deposit (use /wallet/v1/intents/deposit/cross-chain)'
      description: |
        **Deprecated legacy alias.** Use
        [`intentsDepositCrossChain`](#tag/Wallet/operation/intentsDepositCrossChain)
        (`POST /wallet/v1/intents/deposit/cross-chain`) instead. This path is
        retained for backward compatibility and resolves to the same handler
        with identical request/response shapes — existing clients continue to
        work unchanged.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DepositIntentRequest'
      responses:
        '200':
          description: Deposit intent created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositIntentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/intents/deposit/cross-chain/status:
    get:
      tags: [Wallet]
      operationId: getCrossChainDepositStatus
      summary: Poll a cross-chain deposit's status
      description: |
        Returns the live status of a cross-chain deposit (from
        `intentsDepositCrossChain`), lazily refreshing it against 1Click on each
        call.

        **Legacy alias:** `GET /wallet/v1/deposit-status` still works and
        resolves to the same handler.
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
          description: The `intent_id` from `intentsDepositCrossChain`.
      responses:
        '200':
          description: Deposit status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/deposit-status:
    get:
      tags: [Wallet]
      operationId: getDepositStatus
      deprecated: true
      summary: '[Deprecated] Poll a cross-chain deposit''s status (use /wallet/v1/intents/deposit/cross-chain/status)'
      description: |
        **Deprecated legacy alias.** Use
        [`getCrossChainDepositStatus`](#tag/Wallet/operation/getCrossChainDepositStatus)
        (`GET /wallet/v1/intents/deposit/cross-chain/status`) instead. Retained
        for backward compatibility; resolves to the same handler.
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
          description: The `intent_id` from the cross-chain deposit call.
      responses:
        '200':
          description: Deposit status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/intents/deposit/cross-chain/list:
    get:
      tags: [Wallet]
      operationId: listCrossChainDeposits
      summary: List this wallet's cross-chain deposits
      description: |
        Returns the wallet's cross-chain deposits (from
        `intentsDepositCrossChain`), most recent first. Each entry has the same
        shape as `getCrossChainDepositStatus`, but the list endpoint does NOT
        lazily refresh in-flight deposits against 1Click — statuses are read
        straight from storage as last persisted. Poll
        `getCrossChainDepositStatus` for a single deposit when you need its live
        status.

        **Legacy alias:** `GET /wallet/v1/deposits` still works and resolves to
        the same handler.
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            maximum: 100
          description: Max rows to return (server caps at 100). Defaults to 20.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Number of rows to skip for pagination.
      responses:
        '200':
          description: Cross-chain deposits (most recent first)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DepositStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/deposits:
    get:
      tags: [Wallet]
      operationId: listDeposits
      deprecated: true
      summary: '[Deprecated] List cross-chain deposits (use /wallet/v1/intents/deposit/cross-chain/list)'
      description: |
        **Deprecated legacy alias.** Use
        [`listCrossChainDeposits`](#tag/Wallet/operation/listCrossChainDeposits)
        (`GET /wallet/v1/intents/deposit/cross-chain/list`) instead. Retained
        for backward compatibility; resolves to the same handler.
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            maximum: 100
          description: Max rows to return (server caps at 100). Defaults to 20.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Number of rows to skip for pagination.
      responses:
        '200':
          description: Cross-chain deposits (most recent first)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DepositStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  # ============================================================================
  # Payment checks — agent-to-agent gasless payments via ephemeral intents keys
  # ============================================================================
  /wallet/v1/limit-orders:
    post:
      tags: [Wallet]
      operationId: createLimitOrder
      summary: Rest a limit order at a price you set
      description: |
        Rests a swap on 1Click at `price` or better, funded from one of the
        wallet's own balances: its public intents balance (`deposit_type:
        intents`, the default) or its confidential balance (`deposit_type:
        confidential_intents`). The order waits until it fills (partially or
        fully), is cancelled, or reaches its `deadline` (7 days unless you set
        one). Filled output goes to `recipient` — this wallet's own account
        when omitted; the unfilled remainder always comes back to this wallet,
        on the balance the order was funded from. MAINNET only.

        **Funding from the confidential balance** is one mode, taken whole: the
        order is funded from the confidential balance, pays out to the
        confidential balance (`recipient_type` is `confidential_intents` or
        omitted; `intents` or `destination_chain` with it is `400
        bad_request` — mixed routing is not offered) and refunds there. Such
        an order needs the `confidential` capability as well as `limit_order`,
        and the deployment's confidential upstream (`503` otherwise). It is
        funded through 1Click's own funding intent, which this service holds
        to the authorised transfer before the wallet signs it.

        This endpoint is a thin door onto 1Click's `/v0/orders`. The request
        carries 1Click's own order parameters and the answer is 1Click's own
        order, in this API's conventions: **field names in snake_case,
        enumerated values in lower case, nothing renamed or merged**
        (`fillStatus: "PENDING_CANCEL"` arrives as
        `fill_status: "pending_cancel"`). A value 1Click adds later passes
        through as itself.

        **What makes this different from every other exit.** The wallet
        authorises the order ONCE, here. The payout happens later — possibly
        days later — with no further signature from the wallet. Two
        consequences an owner should know before enabling it:

        * **A price through the market fills at once.** A limit order is not a
          gentler thing than a withdrawal; at a bad enough price it is one. It
          is therefore gated like one — see below.
        * **A freeze does not cancel resting orders.** Freezing a wallet takes
          away the ability to place NEW orders (and to do anything else the
          policy gates); orders already resting stay, and keep filling and
          paying out on the terms they were authorised under. Cancelling is
          never frozen, and a freeze does not revoke API keys: the same key
          that placed the orders calls `cancel-all` (or cancels order by
          order) to clear them. Cancelling is asynchronous, and the upstream
          allows a last slice to fill after a cancel is accepted.

        **Security model.** Gated by the default-DENY `limit_order` capability
        AND the `limit_order` transaction type, plus the address rules on
        `recipient` and the per-token amount limit on what the wallet sends — the same
        gates as `cross_chain_withdraw`, which neither stands in for it nor is
        implied by it. The address rules apply to the default recipient too:
        under a `whitelist`, an order paying out to this wallet's own intents
        account needs that account on the list. On a multisig wallet the call answers
        `pending_approval`: approvers sign over the order's terms (input token
        and amount, output token and minimum), and the order is created only
        after the threshold.

        **Amounts.** `quantity` is in the base asset's smallest units. `price`
        is quote per one WHOLE base, a plain decimal string. The wallet sends
        the base on a `sell` and the quote on a `buy`; the terms are computed
        by this service before the order exists, and the upstream's own figures
        must be no worse or the order is cancelled unfunded. Minimum order
        value is 0.1 USD (the upstream's).

        **Fees.** 1Click applies its own app fee to the input (reported back as
        `app_fees`, in basis points). It is not set by this service.

        **Balance.** The wallet's balance of the asset it sends — the one
        `deposit_type` names — is checked before anything is created at
        1Click: short of the order's input, the call answers
        `insufficient_balance` with both figures.

        **The answer** is the order as 1Click described it when it was created
        — `fill_status: awaiting_deposit`, `deposited_amount: "0"` — together
        with `transfer_intent_hash`, the intent that funds it. 1Click picks
        the deposit up within seconds; read the order to see it `open`.

        **Idempotency** is the rest of this API's: a key seen before is not
        executed again and answers `duplicate_idempotency_key`, naming the
        `request_id` it belongs to.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/AnswerWithin'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LimitOrderCreateRequest'
            example:
              base_asset: nep141:wrap.near
              quote_asset: nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1
              side: sell
              quantity: '1000000000000000000000000'
              price: '5'
      responses:
        '200':
          description: >-
            The order was created and funded, is waiting for multisig approval, or
            was created with its funding transfer handed over and unconfirmed
            (`processing`).
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/LimitOrderCreated'
                  - $ref: '#/components/schemas/LimitOrderPendingApproval'
                  - $ref: '#/components/schemas/LimitOrderProcessing'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    get:
      tags: [Wallet]
      operationId: listLimitOrders
      summary: List this wallet's limit orders
      description: >-
        Newest first, paged with `limit` / `offset`, each order as this service
        last recorded it — the list never asks 1Click. An order's record is brought up to date by
        reading it (`GET /wallet/v1/limit-orders/{order_id}`) or cancelling it,
        so poll the one order you are waiting on, not the list.
      parameters:
        - name: open
          in: query
          required: false
          schema: { type: boolean, default: false }
          description: Only orders not yet recorded as finished paying out.
        - name: limit
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
          description: >-
            Page size. A value outside 1..100 is refused with `400`, not cut
            down — page with `offset` for more.
        - name: offset
          in: query
          required: false
          schema: { type: integer, minimum: 0, default: 0 }
      responses:
        '200':
          description: The wallet's orders.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LimitOrder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/limit-orders/cancel-all:
    post:
      tags: [Wallet]
      operationId: cancelAllLimitOrders
      summary: Cancel every order this wallet still has resting
      description: |
        Asks 1Click to cancel every limit order of THIS wallet that is on
        record as not finished — the orders placed through this API with this
        wallet, and nothing else: no other wallet, no other venue. For each
        one matching stops, what already filled is still paid out to the
        order's `recipient`, and the unfilled remainder is refunded to the
        wallet's intents balance. With nothing resting it answers `known: 0`.

        One call asks about at most 50 orders, oldest first. A wallet with more
        gets `remaining` > 0 and `complete: false` — call again until
        `complete` is true. If a batch keeps failing, step over it with
        `offset` to reach the orders behind it; a call with an `offset` never
        answers `complete: true`, because the skipped orders are still resting.

        Never policy-gated and never refused to a frozen wallet: cancelling
        only ever brings funds home. A freeze cancels nothing by itself and
        does not revoke API keys — this call, with the same key as before, is
        how the orders that were resting when a wallet was frozen are
        cleared. Cancelling is asynchronous; read the
        orders back to see them finish. `complete: false` means some order
        could not be reached — call again.
      parameters:
        - name: offset
          in: query
          required: false
          schema: { type: integer, minimum: 0, default: 0 }
          description: Unfinished orders to skip, oldest first.
        - name: limit
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 50, default: 50 }
          description: >-
            How many orders this call asks 1Click about. If 1Click is slow the
            call stops after about a minute and answers `503` saying how many
            cancels were accepted — those stay accepted; call again with a
            smaller `limit`. A value outside 1..50 is refused with `400`.
      responses:
        '200':
          description: How many cancels were asked for and accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitOrderCancelAllResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/limit-orders/{order_id}:
    get:
      tags: [Wallet]
      operationId: getLimitOrder
      summary: Read one limit order
      description: >-
        The order's current state: read from 1Click while it is working, from
        the record once it has finished paying out (it can no longer change).
        `404` for an order that is not this wallet's — an order id is not a
        bearer token.
      parameters:
        - name: order_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitOrder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/limit-orders/{order_id}/cancel:
    post:
      tags: [Wallet]
      operationId: cancelLimitOrder
      summary: Cancel one limit order
      description: |
        Asks 1Click to stop matching the order. Filled output is still paid
        out and the unfilled remainder refunded to this wallet's intents
        balance. Asynchronous and safe to repeat: `fill_status` turns
        `pending_cancel`, the order is finished only when
        `is_payout_status_final` is true, and it may still end `filled` if a
        last slice matched. Never policy-gated — a frozen wallet can always
        cancel.
      parameters:
        - name: order_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The order, as of the cancel being accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitOrder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/payment-check/create:
    post:
      tags: [Wallet]
      operationId: createPaymentCheck
      summary: Create a payment check (bearer-claimable transfer)
      description: |
        Creates a "payment check": the wallet's intents balance is moved to a
        fresh ephemeral intents account (gaslessly, via the solver relay), and
        the ephemeral account's private key is returned as `check_key`. Whoever
        holds `check_key` can `claimPaymentCheck` the funds; the creator can
        `reclaimPaymentCheck` them back. Fund the wallet's intents balance first
        via `intentsDeposit`.

        **Policy.** The keystore signs the transfer-to-ephemeral only when the
        wallet policy grants the default-DENY `payment_check` capability and the
        amount is within the capability's per-token cap. On a wallet with an
        approval threshold the check is held for the approvers like every other
        operation that moves money: the answer is `status=pending_approval` with
        `approval_id`, `required`, `approved` and `request_hash`; the `check_key`
        is returned at once (the account is fixed by the check's counter and
        holds nothing until the threshold); once the threshold is met the
        coordinator funds the check, and `poll_url` reads `unclaimed`. A veto,
        an approval that expires unmet (24 h), or the check's own `expires_at`
        passing while it waits, ends it `failed`. Naming
        `payment_check` in `approval.excluded_types` keeps the capability gate
        without the threshold; `capabilities.payment_check.requires_approval`
        demands it on its own. `claimPaymentCheck` / `reclaimPaymentCheck` are
        signed by the ephemeral `check_key` itself (NEP-413), never by the
        keystore, and need no approval.

        Counted as one `custody:payment_check` operation against the wallet's
        ceiling (429 `operation_limit_reached`, nothing reserved); a claim or a
        reclaim is not counted.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/AnswerWithin'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCheckCreateRequest'
            example:
              token: nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1
              amount: '1000000'
              memo: coffee
              expires_in: 86400
      responses:
        '200':
          description: >-
            Payment check created: `status=unclaimed` once its funding settled,
            `status=creating` with a `poll_url` while the funding transfer is
            unconfirmed, or `status=pending_approval` with `approval_id` and
            `poll_url` while the wallet's approvers decide. The `check_key` is
            returned in every case — keep it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentCheckCreateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/payment-check/batch-create:
    post:
      tags: [Wallet]
      operationId: batchCreatePaymentChecks
      summary: Create up to 10 payment checks in one call
      description: |
        Creates between 1 and 10 payment checks in a single request, each backed
        by its own ephemeral intents account. The wallet's intents balance must
        cover the sum per token across the batch; a batch it does not cover is
        refused whole, before any check is funded. Each check answers as
        `createPaymentCheck` does (`unclaimed`, or `creating` + `poll_url`). If
        the batch stops part way, the checks already created are listed with
        their keys and `error` says why the rest were not created.

        **Policy.** As `createPaymentCheck`: the `payment_check` capability and
        its per-transaction cap, decided — and counted as one
        `custody:payment_check` operation — per check, all before anything is
        reserved. A wallet whose policy requires approval gets no batch:
        `403 policy_denied` ("this wallet's policy requires approval for payment
        checks; create them one at a time") and nothing is created — use
        `createPaymentCheck`, one check per approval. Each check's claim/reclaim
        is signed by that check's ephemeral key, not the keystore.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/AnswerWithin'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCheckBatchCreateRequest'
            example:
              checks:
                - token: nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1
                  amount: '1000000'
                  memo: invoice-1
                - token: nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1
                  amount: '2000000'
      responses:
        '200':
          description: Payment checks created (see `error` for a batch that stopped early)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentCheckBatchCreateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/payment-check/claim:
    post:
      tags: [Wallet]
      operationId: claimPaymentCheck
      summary: Claim a payment check
      description: |
        Claims the funds held by a payment check into the authenticated wallet's
        intents balance. Signed by the ephemeral `check_key` (NEP-413), so the
        caller need only hold the key. Omit `amount` for a full claim, or pass a
        partial amount (minimal units) to claim part and leave the remainder
        claimable. Expired or already-settled checks are rejected, and so is a
        check with another claim or reclaim in flight, one still `creating`,
        and one still `pending_approval` (`400 bad_request`: "Check is awaiting
        the owner's approval" — nothing is in its account yet).

        When the transfer is not confirmed in time — or the call fails after
        handing it over — the answer is `status=processing` with `request_id`
        and `poll_url` (`GET /wallet/v1/requests/{request_id}`), never an error:
        the transfer may land, and the request settles from the chain.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/AnswerWithin'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCheckClaimRequest'
            example:
              check_key: 9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a
      responses:
        '200':
          description: Claim settled, or `processing` until its transfer is confirmed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentCheckClaimResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/payment-check/reclaim:
    post:
      tags: [Wallet]
      operationId: reclaimPaymentCheck
      summary: Reclaim an unclaimed payment check
      description: |
        Returns the (remaining) funds of a payment check the wallet created back
        to the wallet's own intents balance — used to cancel/expire a check that
        was never claimed. Identified by `check_id` and scoped to the creating
        wallet. Signed by the ephemeral check key (re-derived inside the
        keystore), not the keystore's wallet key. Omit `amount` for a full
        reclaim or pass a partial amount. Answers `processing` + `poll_url` as
        `claimPaymentCheck` does, and refuses a check still `pending_approval`
        as it does.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/AnswerWithin'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCheckReclaimRequest'
            example:
              check_id: 3a2b1c0d-4e5f-6a7b-8c9d-0e1f2a3b4c5d
      responses:
        '200':
          description: Reclaim settled, or `processing` until its transfer is confirmed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentCheckReclaimResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/payment-check/status:
    get:
      tags: [Wallet]
      operationId: getPaymentCheckStatus
      summary: Get a payment check's status
      description: |
        Returns the full lifecycle state of a payment check the wallet created,
        identified by `check_id`. `status` is normalized to `expired` when an
        `unclaimed` check is past its `expires_at`.
      parameters:
        - name: check_id
          in: query
          required: true
          schema:
            type: string
          description: The `check_id` returned by `createPaymentCheck`.
      responses:
        '200':
          description: Payment check status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentCheckStatusResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/payment-check/list:
    get:
      tags: [Wallet]
      operationId: listPaymentChecks
      summary: List the wallet's payment checks
      description: |
        Lists payment checks created by the authenticated wallet, most recent
        first. Optionally filter by `status` (including the virtual `expired`
        status: unclaimed checks past their `expires_at`).
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
          description: >-
            Optional status filter. Accepts stored statuses (`pending_approval`,
            `creating`, `unclaimed`, `claiming`, `claimed`, `partially_claimed`,
            `reclaiming`, `reclaimed`, `partially_reclaimed`, `failed`) plus the
            virtual `expired` (unclaimed + past expiry).
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
            maximum: 100
          description: Max rows to return (server caps at 100). Defaults to 50.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Number of rows to skip for pagination.
      responses:
        '200':
          description: Payment checks (most recent first)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentCheckListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/payment-check/peek:
    post:
      tags: [Wallet]
      operationId: peekPaymentCheck
      summary: Inspect a payment check by its key (without claiming)
      description: |
        Reads a payment check's on-chain balance and metadata using its
        `check_key`, without moving any funds. Use this before
        `claimPaymentCheck` to see what a key is worth. Returns the live
        on-chain `balance` of the ephemeral account plus the stored `token` /
        `memo` / `status` / `expires_at`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCheckPeekRequest'
            example:
              check_key: 9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a
      responses:
        '200':
          description: Payment check snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentCheckPeekResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/sign-message:
    post:
      tags: [Wallet]
      operationId: signMessage
      summary: Sign a generic NEP-413 message
      description: |
        Signs a NEP-413 message with the wallet's NEAR key (e.g. dApp login).
        Gated by the `sign_message` capability: `allowed_recipients` is a
        default-DENY allowlist of verifier recipients, and `intents.near` /
        `intents.far` are always excluded. Policy and freeze still apply — a
        frozen wallet cannot sign.

        **`format` is now NEP-413 only.** `format=raw` is **rejected** with
        `400 bad_request` — OutLayer NEAR-key auth (the old raw-ed25519
        `auth:`/`register:`/`api-key:` token) moved to
        [`POST /wallet/v1/auth-sign`](#tag/Wallet/operation/authSign), which
        builds the challenge with a fresh server timestamp. This is NOT OutLayer
        auth signing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignMessageRequest'
            example:
              message: 'login:myapp:1716200000'
              recipient: myapp.example
              format: nep413
      responses:
        '200':
          description: Signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignMessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/OperationLimitReached'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/auth-sign:
    post:
      tags: [Wallet]
      operationId: authSign
      summary: Sign an OutLayer NEAR-key auth challenge (Bearer / register / api-key)
      description: |
        Produces the OutLayer authentication signature used to construct a
        `Bearer near:` token, or to authenticate `POST /register` /
        `PUT /wallet/v1/api-key` from a deterministic wallet's own NEAR key.

        The keystore **builds** the exact challenge string
        `<prefix>:<seed>:<ts>` (where `prefix` is `auth` for `bearer`, else the
        purpose) with a **fresh server timestamp** and signs it raw ed25519. The
        client does NOT supply or control the timestamp — the fresh `ts` is what
        the coordinator's verifier requires. Send the returned `auth_message`
        verbatim.

        This is the replacement for the old
        `POST /wallet/v1/sign-message {format:"raw"}`. It maps to an always-allowed,
        non-fund `Op::Auth` (domain-separated from a tx hash) — no capability and
        no multisig gate it, but a frozen wallet still cannot sign.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthSignRequest'
            examples:
              bearer:
                summary: Bearer-near auth token
                value:
                  purpose: bearer
                  seed: my-app-session
              register:
                summary: Authenticate POST /register
                value:
                  purpose: register
                  seed: my-app-session
              apiKey:
                summary: Authenticate PUT /api-key
                value:
                  purpose: api-key
                  seed: my-app-session
      responses:
        '200':
          description: Auth signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthSignResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  # ============================================================================
  # Requests (async tracking)
  # ============================================================================
  /wallet/v1/requests:
    get:
      tags: [Requests]
      operationId: listRequests
      summary: List async wallet requests
      parameters:
        - name: type
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/RequestType'
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/RequestStatus'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
            maximum: 100
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Request list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/requests/{id}:
    get:
      tags: [Requests]
      operationId: getRequest
      summary: Get a single request's status
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Request status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  # ============================================================================
  # Policy
  # ============================================================================
  /wallet/v1/policy:
    get:
      tags: [Policy]
      operationId: getPolicy
      summary: Get current decrypted policy
      description: |
        Returns the wallet's current policy (decrypted by the keystore TEE),
        plus the current usage counters used by velocity-limit checks.

        `policy` states whether a policy exists at all: `none` — no policy is
        stored and every operation is allowed; `stored` — the `rules`,
        `approval`, `capabilities` and `authorized_key_hashes` fields are the
        policy as written. A response without `policy` could not read the
        chain; it says nothing about the policy rather than guessing.

        `version` and `locked` are the policy's state on chain: the version
        the next `store_wallet_policy` must exceed by one, and whether that
        write (and a delete) needs the approvers' quorum. Both absent when the
        chain could not be read.
      responses:
        '200':
          description: Current policy + usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/encrypt-policy:
    post:
      tags: [Policy]
      operationId: encryptPolicy
      summary: Encrypt a policy for on-chain storage
      description: |
        Sends a policy JSON to the keystore TEE for encryption. The returned
        `encrypted_base64` is what gets stored in NEAR via
        `store_wallet_policy(...)` after the keystore signs it; `policy_hash`
        is the sha256 of the canonical plaintext that was encrypted — what a
        locked policy's approvers vote on.

        `approval.locked: true` is accepted only with a reachable quorum —
        `threshold` of at least 1 and at least that many approvers with an
        `id` — and is otherwise `400 invalid_request`: a lock nobody could
        lift is never stored.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EncryptPolicyRequest'
      responses:
        '200':
          description: Encrypted policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EncryptPolicyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/sign-policy:
    post:
      tags: [Policy]
      operationId: signPolicy
      summary: Sign an encrypted policy (for on-chain submission)
      description: |
        The keystore signs the message the contract rebuilds —
        `store_wallet_policy:v2:{wallet_pubkey}:{version}:{locked}:{valid_until}:{len}:{encrypted_data}:{caller}` —
        with the wallet's key. The signature, the encrypted data, the public
        key, and the `version`, `locked` and `valid_until` the answer carries
        form the payload for the on-chain `store_wallet_policy(...)` call:
        pass all three exactly as answered, they are inside the signature.
        `valid_until` is seven days from signing; the contract refuses the
        signature after it.

        `caller` is the account that will SEND that call, and it is signed: the
        answer works for that account and no other. Sending the prepared payload
        from anywhere else is refused on chain. `version` is the chain's plus
        one, so the answer is good for exactly one write.

        **A locked policy.** When the policy on chain carries
        `approval.locked`, the keystore signs only with that policy's
        approvers' quorum. This call then answers `status: pending_approval`
        with the `approval_id` the approvers vote on (`approve` /
        `reject`, as for any pending operation; `request_data.policy` is the
        new policy they are approving) and a `request_id`. Once the threshold
        is met the signature is on `GET /wallet/v1/requests/{request_id}`
        (`status: success`, `result.wallet_signature`, `version`,
        `locked`, `valid_until`, `encrypted_data`); the owner sends
        `store_wallet_policy` with it, within `valid_until`. A vote the keystore does not count, or a policy that moved
        on under the approval, fails the request with the keystore's words.
        The first policy of a wallet, and any write over an unlocked policy,
        is signed at once.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignPolicyRequest'
      responses:
        '200':
          description: The signature, or the approval the write waits on.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignPolicyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/invalidate-cache:
    post:
      tags: [Policy]
      operationId: invalidatePolicyCache
      summary: Invalidate negative policy cache
      description: |
        Forces the coordinator to drop its cached `no_policy` flag for a wallet.
        Call this after submitting `store_wallet_policy(...)` on-chain so that
        subsequent operations pick up the new policy without waiting for the
        5-minute TTL to expire.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvalidateCacheRequest'
      responses:
        '200':
          description: Cache cleared
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  # ============================================================================
  # Approvals (multisig)
  # ============================================================================
  /wallet/v1/pending_approvals:
    get:
      tags: [Approvals]
      operationId: listPendingApprovals
      summary: List pending multisig approvals
      description: |
        The pending approvals of the wallet the `wk_` key (`Authorization:
        Bearer`) belongs to — the agent's own view of what waits on it. Answers
        `{"approvals": [...]}` with only the approvals still `pending` and not
        expired (an approval lives 24 hours). A key lists its own wallet only;
        the owner sees one wallet's queue, by its key, inside an owner's
        session (`GET /wallet/v1/pending_approvals_by_pubkey`).
      responses:
        '200':
          description: Pending approvals
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendingApprovalsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/pending_approvals_by_pubkey:
    get:
      tags: [Approvals]
      operationId: listPendingApprovalsOfWallet
      summary: What waits for approval on one wallet, for its owner
      description: |
        The pending approvals of the wallet `near_pubkey`, for the dashboard's
        bell and inbox. Told inside an owner's session (`POST /inbox/session`)
        and to the wallet's owner only: the session's account is the owner of
        the wallet's policy on the contract. The answer carries each operation
        whole (`op`, `op_canonical`), so nobody else is given it.
      security:
        - OwnerSession: []
      parameters:
        - name: near_pubkey
          in: query
          required: true
          description: The wallet's public key, as `get_wallet_policies_by_owner` lists it.
          schema:
            type: string
      responses:
        '200':
          description: Pending approvals of the wallet; an empty list when nothing waits
          content:
            application/json:
              schema:
                type: object
                required: [near_pubkey, pending_approvals]
                properties:
                  near_pubkey: { type: string }
                  pending_approvals:
                    type: array
                    items:
                      $ref: '#/components/schemas/PendingApproval'
        '401':
          description: >
            No session, or one that ended (`session_required`); or one that
            ended because the account signed in elsewhere (`session_replaced`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                session_required:
                  value: { error: session_required }
                session_replaced:
                  value: { error: session_replaced }
        '403':
          description: The session's account does not own the wallet (`not_wallet_owner`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_wallet_owner:
                  value: { error: not_wallet_owner }
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          description: The database or the chain did not answer; `Retry-After` says when to come back
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /wallet/v1/approval/{id}:
    get:
      tags: [Approvals]
      operationId: getApprovalDetail
      summary: Get a single pending approval's detail
      description: |
        One approval, for the page and the program an approver votes with.
        Told to whoever holds the approval's id, which is random and is handed
        to an approver by the wallet's owner or by the webhook; rate-limited
        by IP. The approvals waiting on a wallet are listed to the wallet's
        own key (`GET /wallet/v1/pending_approvals`) and to its owner inside
        an owner's session (`GET /wallet/v1/pending_approvals_by_pubkey`). The
        `wallet_pubkey` and `request_hash` are the values an approver binds
        into the NEP-413 vote message
        (`approve:{id}:{wallet_pubkey}:{request_hash}` /
        `reject:{id}:{wallet_pubkey}:{request_hash}`); the dashboard renders `op`.
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Approval detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalDetail'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /wallet/v1/approve/{id}:
    post:
      tags: [Approvals]
      operationId: approveRequest
      summary: Approve a pending action
      description: |
        Submits an approver's vote for a pending action: a NEP-413 signature by
        one of the approver's full-access keys, or, for an approver without keys, an
        authorization its wallet contract resolves (`ContractVoteAuth`). When
        the approval threshold is reached, the action auto-executes. No API key
        required — the vote itself proves who cast it.
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveRequest'
      responses:
        '200':
          description: Approval recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApproveResponse'
        '400':
          description: |
            `bad_request`: both proofs or neither; or a contract vote from an
            account that does not run a wallet build this deployment accepts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: |
            `invalid_signature`: the NEP-413 signature does not verify, or
            `public_key` is not a full-access key of `account_id` on chain (a
            vote is signed by the wallet of the account it names; a
            function-call key, held by applications the owner logged into,
            does not vote); or the approver's
            wallet did not resolve the authorization to this vote's message —
            the message names the wallet's own reason.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            `not_approver`: the account is not an approver this wallet's
            policy admits for this vote — not listed, or pinned to another key,
            or pinned at all for a contract-wallet vote. Decided on the policy
            as the chain holds it; nothing is stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: |
            `already_approved`: this account has already voted on this
            approval, approve or reject. One vote per account.
            `conflict`: the approval is no longer pending (approved, rejected
            or expired); the message names its state. Stop; do not retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /wallet/v1/reject/{id}:
    post:
      tags: [Approvals]
      operationId: rejectRequest
      summary: Reject a pending action
      description: |
        A NO vote, proven the same two ways as an approve vote. A reject from a
        policy approver vetoes the action.
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RejectRequest'
      responses:
        '200':
          description: Reject vote recorded (request cancelled if from a real approver)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RejectResponse'
        '400':
          description: |
            `bad_request`: both proofs or neither; or a contract vote from an
            account that does not run a wallet build this deployment accepts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: |
            `invalid_signature`: the NEP-413 signature does not verify, or
            `public_key` is not a full-access key of `account_id` on chain (a
            vote is signed by the wallet of the account it names; a
            function-call key, held by applications the owner logged into,
            does not vote); or the approver's
            wallet did not resolve the authorization to this vote's message —
            the message names the wallet's own reason.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            `not_approver`: the account is not an approver this wallet's
            policy admits for this vote — not listed, or pinned to another key,
            or pinned at all for a contract-wallet vote. Decided on the policy
            as the chain holds it; nothing is stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: |
            `already_approved`: this account has already voted on this
            approval, approve or reject. One vote per account.
            `conflict`: the approval is no longer pending (approved, rejected
            or expired); the message names its state. Stop; do not retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  # ============================================================================
  # Audit
  # ============================================================================
  /wallet/v1/audit:
    get:
      tags: [Audit]
      operationId: listAuditEvents
      summary: Event history for the wallet
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
            maximum: 100
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Event list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  # ============================================================================
  # Execution
  # ============================================================================
  /inbox/session:
    post:
      tags: [Inbox]
      operationId: openOwnerSession
      summary: Sign in on a device
      description: |
        Opens a session from one statement the owner's wallet signed (NEP-413,
        recipient: the OutLayer contract, a fresh 32-byte nonce):

            Sign in to OutLayer as {account_id}. Device key: {device_pubkey}. Valid until {valid_until as YYYY-MM-DDTHH:MM:SSZ}.

        The sentence is rebuilt here from the three fields, so what was signed
        is exactly it. The key that signed must be a full-access key of the
        account on chain; an implicit account (64 hex) that is not on chain
        yet is signed for by its own key. A custody wallet signs with
        `POST /wallet/v1/sign-message` (`recipient`: the OutLayer contract);
        its `signature_base64`, `public_key` and `nonce` are the three fields
        here. One statement opens one session. An account has
        five devices in force at most, each with a session of its own; one
        more retires the device signed in longest ago, which is answered 401
        `session_replaced` from then on.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OwnerSignIn'
      responses:
        '200':
          description: The session. `token` is returned this once.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnerSession'
        '400':
          $ref: '#/components/responses/InboxRefused'
        '429':
          $ref: '#/components/responses/InboxTooManyRequests'
        '503':
          $ref: '#/components/responses/InboxUnavailable'
    delete:
      tags: [Inbox]
      operationId: closeOwnerSession
      summary: Sign out of this device
      security:
        - OwnerSession: []
      responses:
        '200':
          description: The device is withdrawn and its session ended
          content:
            application/json:
              schema:
                type: object
                required: [revoked]
                properties:
                  revoked: { type: boolean }
        '401':
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'

  /inbox/tasks:
    get:
      tags: [Inbox]
      operationId: listInboxTasks
      summary: The owner's tasks, of every project
      security:
        - OwnerSession: []
      parameters:
        - name: show
          in: query
          required: false
          description: "`waiting` — what waits for the owner and what is being acted on; `closed` — the outcomes kept, 30 days."
          schema:
            type: string
            enum: [waiting, closed]
            default: waiting
      responses:
        '200':
          description: The tasks; an empty list when there are none
          content:
            application/json:
              schema:
                type: object
                required: [tasks, more]
                properties:
                  tasks:
                    type: array
                    description: The newest, 200 at most.
                    items:
                      $ref: '#/components/schemas/InboxTask'
                  more:
                    type: boolean
                    description: More exist than are listed; the list is not whole.
        '400':
          $ref: '#/components/responses/InboxRefused'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '429':
          $ref: '#/components/responses/InboxTooManyRequests'
        '503':
          $ref: '#/components/responses/InboxUnavailable'
    delete:
      tags: [Inbox]
      operationId: deleteInboxTasks
      summary: Delete every task addressed to the owner
      description: In any state. Narrowed to an agent's or a project's tasks when the query names one.
      security:
        - OwnerSession: []
      parameters:
        - name: preparer
          in: query
          required: false
          schema: { type: string }
        - name: project_uuid
          in: query
          required: false
          schema: { type: string }
      responses:
        '200':
          description: How many were deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxDeleted'
        '400':
          $ref: '#/components/responses/InboxRefused'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'

  /inbox/tasks/{id}:
    delete:
      tags: [Inbox]
      operationId: deleteInboxTask
      summary: Delete one task, in any state
      security:
        - OwnerSession: []
      parameters:
        - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxDeleted'
        '400':
          $ref: '#/components/responses/InboxRefused'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '404':
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'

  /inbox/tasks/{id}/files/{n}:
    get:
      tags: [Inbox]
      operationId: getInboxTaskFile
      summary: One file of a task that waits
      description: |
        A file the owner is given to open beside the task's fields, as
        ciphertext: `0x01 || nonce (12) || AES-256-GCM` under the task's
        content key, bound to `{task id}:file:{n}`. The task's envelope names
        each file's `name`, `content_type`, `size` and `sha256`; a page holds
        the bytes it opened to that size and hash, and hands the file to the
        owner as a download.
      security:
        - OwnerSession: []
      parameters:
        - $ref: '#/components/parameters/TaskId'
        - name: n
          in: path
          required: true
          description: The file's place among the task's files, from 0.
          schema:
            type: integer
            minimum: 0
            maximum: 9
      responses:
        '200':
          description: The file
          content:
            application/json:
              schema:
                type: object
                required: [ciphertext]
                properties:
                  ciphertext:
                    type: string
                    contentEncoding: base64
        '400':
          $ref: '#/components/responses/InboxRefused'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '404':
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'

  /inbox/tasks/{id}/origin:
    get:
      tags: [Inbox]
      operationId: getInboxTaskOrigin
      summary: The run that made a task, what it was asked and what it answered
      description: |
        With the run's attestation — public, at
        `GET /attestations/by-call/{call_id}` or
        `GET /attestations/by-request/{request_id}` — this is what a page
        needs to tell that a task was made by a published build of its
        project. The attestation names the build that ran and the SHA-256 of
        the run's input and of its answer; `input` and `output` are those
        bytes, byte for byte; and the answer names the task's id and
        `task_hash`. A request on chain carries its input and its answer in
        its transaction, so both are `null` for it.
      security:
        - OwnerSession: []
      parameters:
        - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: The run
          content:
            application/json:
              schema:
                type: object
                required: [run, door, output, input]
                properties:
                  run: { type: string }
                  door: { type: string, enum: [https, chain] }
                  call_id: { type: string, format: uuid, description: "With `door: https`." }
                  request_id: { type: integer, description: "With `door: chain`." }
                  output:
                    type: [string, 'null']
                    description: |
                      What the run answered, as the bytes the attestation's
                      `output_hash` is the SHA-256 of. Present for a call over
                      HTTPS that completed; `null` for a request on chain.
                  input:
                    type: [string, 'null']
                    description: |
                      What the run was asked, as the bytes the attestation's
                      `input_hash` is the SHA-256 of: the call's `input` as the
                      coordinator serialised it, keys in the order the caller
                      sent them. Present for a call over HTTPS; `null` for a
                      request on chain, whose transaction carries it.
        '400':
          $ref: '#/components/responses/InboxRefused'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '404':
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'

  /inbox/tasks/{id}/reject:
    post:
      tags: [Inbox]
      operationId: rejectInboxTask
      summary: Say no to a task, with a reason
      description: |
        No run. The reason is encrypted by the page to the task's
        `reply_pubkey` (purpose `rejection`), so it is ciphertext here and the
        agent's next run reads it.
      security:
        - OwnerSession: []
      parameters:
        - $ref: '#/components/parameters/TaskId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  type: [string, 'null']
                  contentEncoding: base64
                  description: The reason, encrypted to the task's `reply_pubkey`; at most 8192 bytes.
      responses:
        '200':
          description: Rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxTaskMoved'
        '400':
          description: "`invalid_request`: the reason is empty or over its bound, or the task is a notice — Got it closes it."
          $ref: '#/components/responses/InboxRefused'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '404':
          $ref: '#/components/responses/InboxRefused'
        '409':
          description: "`task_closed` with `state`: an `approved` task cannot be rejected — the owner said yes and a run may be acting."
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'

  /inbox/tasks/{id}/acknowledge:
    post:
      tags: [Inbox]
      operationId: acknowledgeInboxTask
      summary: Got it — close a notice as seen
      description: |
        The session alone: no wallet signature, no run. An open notice of the
        owner's is `done`; what it showed is deleted, as with every close, and
        its preparer reads it `done`. No event is sent for it. A task that is
        not a notice is approved or rejected, not acknowledged: 400.
      security:
        - OwnerSession: []
      parameters:
        - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: Seen
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxTaskMoved'
        '400':
          description: "`invalid_request`: the task is not a notice."
          $ref: '#/components/responses/InboxRefused'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '404':
          $ref: '#/components/responses/InboxRefused'
        '409':
          description: "`task_closed` with `state`: the notice is not `open` — seen, cancelled or expired already."
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'

  /inbox/tasks/{id}/approve:
    post:
      tags: [Inbox]
      operationId: approveInboxTask
      summary: Say yes to a task, with one signature of the wallet
      description: |
        No run of the owner's and no transaction. The owner's wallet signs one
        NEP-413 message (recipient: the OutLayer contract; a fresh 32-byte
        nonce; a full-access key of the account):

            Approve in OutLayer as <account>: task <id> with hash <task_hash> and supply <digest>. At <YYYY-MM-DDTHH:MM:SSZ>.

        `<task_hash>` is the SHA-256, lowercase hex, of the envelope the page
        opened. `<digest>` is the SHA-256, hex, of the canonical JSON
        `{"note":<base64|null>,"supplied":<base64|null>}` over `supplied` and
        `note` exactly as this request sends them (members in that order,
        standard base64, no whitespace); with neither it is the digest of
        `{"note":null,"supplied":null}`. `<at>` is the minute the signature
        names, good within ten minutes of the server's clock, once.

        On a signature that holds the task is `approved` and the platform
        starts a run of the AGENT that prepared it, on the agent's own payment
        key, wallet and identity, within the compute limit of the preparing
        run, in the operation the task names, with the approval in its input.
        The enclave verifies the same signature before the run acts. The
        answer names that run. A run that cannot be started fails the task at
        once: `state: failed` with `failure_reason`, and the agent prepares
        again.
      security:
        - OwnerSession: []
      parameters:
        - $ref: '#/components/parameters/TaskId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [task_hash, approval]
              properties:
                task_hash:
                  type: string
                  pattern: '^[0-9a-f]{64}$'
                  description: SHA-256 of the envelope the page opened, lowercase hex.
                approval:
                  $ref: '#/components/schemas/OwnerConfirmation'
                supplied:
                  type: [string, 'null']
                  contentEncoding: base64
                  description: "What the owner supplies (an `input` task), encrypted to the task's `reply_pubkey` with purpose `answer`; at most 8192 bytes."
                note:
                  type: [string, 'null']
                  contentEncoding: base64
                  description: "What the owner wrote beside the approval, encrypted to `reply_pubkey` with purpose `note`; at most 8192 bytes. Handed to the project's code with the answer."
      responses:
        '200':
          description: "Approved, with the run started — or failed at once, with the reason."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxTaskMoved'
        '400':
          description: "`invalid_request`: a hash that is not one, a supply that the task's kind does not take, or a notice, which takes no answer — judged before the signature is spent."
          $ref: '#/components/responses/InboxRefused'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '403':
          description: "`confirmation_required`: the signature does not hold, is older than ten minutes, was signed by a key that is not a full-access key of the account, or was spent."
          $ref: '#/components/responses/InboxRefused'
        '404':
          $ref: '#/components/responses/InboxRefused'
        '409':
          description: "`task_closed` with `state`: the task is not `open`. `task_ending`: the task ends in under five minutes, too soon for its run to take it — refused before the signature is spent; ask the agent to prepare it again."
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'

  /inbox/mutes:
    get:
      tags: [Inbox]
      operationId: listInboxMutes
      summary: Whom the owner silenced
      security:
        - OwnerSession: []
      responses:
        '200':
          description: The agents and projects whose tasks are refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxMutes'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'
    post:
      tags: [Inbox]
      operationId: muteInInbox
      summary: Silence an agent or a project
      description: Its next task is refused `muted`. With `delete_waiting`, its tasks already addressed to the owner are deleted at once.
      security:
        - OwnerSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [subject_is, subject]
              properties:
                subject_is: { type: string, enum: [agent, project] }
                subject: { type: string, description: An account id for an agent; a uuid for a project. }
                delete_waiting: { type: boolean, default: false }
      responses:
        '200':
          description: Muted; how many tasks were deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxDeleted'
        '400':
          $ref: '#/components/responses/InboxRefused'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'
    delete:
      tags: [Inbox]
      operationId: unmuteInInbox
      summary: Let an agent or a project write again
      security:
        - OwnerSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxMute'
      responses:
        '200':
          description: The mutes that remain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxMutes'
        '400':
          $ref: '#/components/responses/InboxRefused'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'

  /inbox/webhook:
    get:
      tags: [Inbox]
      operationId: getInboxWebhook
      summary: Where the owner is told of a task
      security:
        - OwnerSession: []
      responses:
        '200':
          description: The URL, or `null`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxWebhook'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'
    put:
      tags: [Inbox]
      operationId: setInboxWebhook
      summary: Name the URL task events go to
      description: |
        `task_created`, `task_approved`, `task_answered`, `task_failed`
        (with `failure_reason`) and `task_expired` are POSTed there,
        signed with a secret of the owner's own (`X-Webhook-Signature`, the
        HMAC-SHA256 of the body in hex), with `X-Wallet-Id: owner:{account}`.
        The secret is in the answer to this call and nowhere else. A body says who asked whom, of what
        kind and when, and links to the inbox; nothing of what the task shows.
        A notice is told as `task_created` with `kind: notice`; Got it sends
        nothing.
        The URL is an HTTPS URL on a public host, without credentials in it;
        the sender follows no redirect. The URL stays in force when the
        session that named it ends, and says which session that was.

        Naming the URL takes the owner's signature beside the session (see
        `OwnerConfirmation`): the sentence names the URL by its SHA-256.
        Without one that holds: 403 `confirmation_required`.
      security:
        - OwnerSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [url, confirmation]
              properties:
                url: { type: string, format: uri, description: "An HTTPS URL on a public host, without credentials." }
                confirmation:
                  $ref: '#/components/schemas/OwnerConfirmation'
      responses:
        '200':
          description: The URL now in force
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxWebhook'
        '400':
          $ref: '#/components/responses/InboxRefused'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'
    delete:
      tags: [Inbox]
      operationId: deleteInboxWebhook
      summary: Stop the events
      description: Takes the owner's signature for `remove the webhook` (see `OwnerConfirmation`).
      security:
        - OwnerSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [confirmation]
              properties:
                confirmation:
                  $ref: '#/components/schemas/OwnerConfirmation'
      responses:
        '200':
          description: No URL is in force
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxWebhook'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'

  /inbox/devices:
    get:
      tags: [Inbox]
      operationId: listOwnerDevices
      summary: The owner's devices in force
      security:
        - OwnerSession: []
      responses:
        '200':
          description: The devices
          content:
            application/json:
              schema:
                type: object
                required: [devices]
                properties:
                  devices:
                    type: array
                    items:
                      $ref: '#/components/schemas/OwnerDevice'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'

  /inbox/devices/{id}:
    delete:
      tags: [Inbox]
      operationId: withdrawOwnerDevice
      summary: Withdraw a device
      description: |
        Its session ends and no task is encrypted to it from now on. A device
        that is lost with the wallet key that signed it in is cut off for
        certain by removing that key (`signer_pubkey`) from the account on
        chain: every statement it signed stops holding, whatever is stored here.

        The session's own device signs out on its token alone. Another device
        of the account takes the owner's signature for
        `withdraw the device {id}` (see `OwnerConfirmation`); without one that
        holds: 403 `confirmation_required`.
      security:
        - OwnerSession: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                confirmation:
                  $ref: '#/components/schemas/OwnerConfirmation'
      responses:
        '200':
          description: Whether a device of the owner's was withdrawn
          content:
            application/json:
              schema:
                type: object
                required: [revoked]
                properties:
                  revoked: { type: boolean }
        '400':
          $ref: '#/components/responses/InboxRefused'
        '401':
          $ref: '#/components/responses/InboxRefused'
        '503':
          $ref: '#/components/responses/InboxUnavailable'

  /call/{owner}/{project}:
    post:
      tags: [Execution]
      operationId: callProject
      summary: Run a project, or a connector
      description: |
        One route for every project. A **connector** is an ordinary project we
        curated and priced; what being one adds is decided from the project id,
        not from the way in.

        A connector call MUST name its operation as a top-level `operation`
        string inside `input`. The same bytes are read by four parties — the
        contract prices the call, the coordinator bills it, the worker refuses
        to run without it, and the guest dispatches on it — so there is one
        value and nothing to keep in step. Absent, blank, non-string, nested, or
        spelled `op` are all refused before anything runs, and an operation with
        no on-chain price is refused too: unpriced is not free.

        **Waiting.** Synchronous by default: the connection is held until the
        run finishes or the server's window elapses. Send `"async": true` for
        anything longer — it returns at once with `call_id` and `poll_url`, and
        that path has no window at all. A synchronous call that outruns the
        window is settled, not suspended: `408`, charged for the compute
        authorised and never for the operation. Do not retry it — the original
        may still be running and will be charged.
      security:
        - PaymentKeyAuth: []
      parameters:
        - name: owner
          in: path
          required: true
          schema: { type: string }
          description: Project owner account, e.g. `connectors.outlayer.near`.
        - name: project
          in: path
          required: true
          schema: { type: string }
        - name: X-Use-Owner-Secret
          in: header
          required: false
          schema: { type: string, enum: ['1', 'true'] }
          description: |
            Fetch the secret stored for this agent and inject it into the run.
            Nothing is looked up unless the call asks. Only meaningful for a key
            owned by a custody wallet; an ordinary payment key addresses its own
            secrets through the body.
        - name: X-Attached-Deposit
          in: header
          required: false
          schema: { type: string }
          description: Stablecoin minimal units paid to the project's owner. Refused for connectors.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectCallRequest'
      responses:
        '200':
          description: |
            The run finished, or was accepted for polling when `async`. A synchronous call
            the API restarted during answers `pending` with `poll_url`: it was not resent and
            is still running — read it there, do not send it again (it would run and be
            charged twice).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectCallResponse'
        '400':
          description: |
            The request itself is wrong; `reason` says how:
            `invalid_secrets_ref` (the body's `secrets_ref` names a row the
            contract could never hold — see `ProjectCallRequest.secrets_ref`),
            `invalid_version_key`, `bad_key_format`, `max_per_call_exceeded`,
            `compute_limit_too_low`. A body that is not JSON at all is
            answered by the framework with a plain-text 400 (and a missing
            JSON content type with 415), not with this schema.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallRefusal'
        '402':
          description: |
            The key cannot pay for this call. `reason` says which way:

            * `trial_exhausted` — a TRIAL key has made its calls (`used`, `limit`).
              **`terminal: true`**. Create a payment key with money on it
              (`POST /wallet/v1/create-payment-key`) — a funded key has no call
              limit;
            * `trial_expired` — a TRIAL key past the wallet's first week
              (`expires_at`), with calls left or not. **`terminal: true`**, and
              the same next step. A trial stops starting calls shortly before
              `expires_at`, so that none is cut off mid-run;
            * `insufficient_balance`, `out_of_funds`, `insufficient_allowance` —
              money, as their names say;
            * `expires_too_soon` — the subscription ends before this operation
              could finish; extend it;
            * `allowance_no_deposit` — `X-Attached-Deposit` on a call paid from
              an allowance, which is not money and cannot be paid to a developer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallRefusal'
        '403':
          description: |
            The key may not make this call. By `reason`: `project_not_allowed`
            — its scope does not include this project; `no_deposit` — a key whose
            value was given (a trial, a grant) sent `X-Attached-Deposit`;
            `policy_row_not_owner` — a trading connector was given a policy row
            that is not the wallet owner's; `calls_suspended` — the wallet is
            blocked on the trading connectors for a while;
            `tee_session_required`, `vault_not_verified`, `wallet_not_yours` —
            the wallet or vault named does not stand behind this caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallRefusal'
        '408':
          description: |
            The call did not finish inside the synchronous window and has been
            settled as failed. Terminal — send it as `async` and poll instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallTimedOut'
        '409':
          description: |
            `no_bound_identity` — the call asked to run as a bound account with
            `use_bound_identity`, and there is none to run as: either the paying
            key names no wallet (`terminal: true`), or the wallet has no ACTIVE
            binding (`terminal: false` — a pending or revoked binding authorizes
            nothing, and one that activates later makes the same call work).

            Refused before the call is priced or charged, and never answered by
            running the job under the caller's own name: which account the guest
            IS decides what a connector does with it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallRefusal'
        '503':
          description: |
            `upstream_unavailable` — something this call depends on has not
            caught up yet, or this deployment's database could not serve the
            request right now, and the same call works later. `keystore_error` —
            the TEE keystore was unreachable or refused to sign. Both are
            transient and both are sent with a `Retry-After` interval. Sent
            only before the job is queued: nothing ran and nothing was charged,
            so resending is safe.

            Deliberately not `service_unavailable`: on `/wallet/v1/*` that code
            means a feature this deployment does not offer and carries no
            interval, and one product must not use one code for "come back" and
            "never come back".
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallRefusal'
        '500':
          description: |
            `internal_error` — a failure on our side, with a fixed sentence and
            no `Retry-After`. A synchronous call whose job was already queued
            answers this, never `503`, when the database fails while it waits:
            the job may still run and be charged, and `/call` takes no
            idempotency key, so a resend would run — and bill — a second call.
            Do not resend it blindly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallRefusal'
        '429':
          description: |
            Three different refusals share this status, and a caller tells them
            apart by `reason` rather than by the code:

            * `call_already_in_flight` — an ALLOWANCE runs one call at a time
              (a sponsored key: as many as its code's `max_parallel`).
              **`terminal: false`**: it clears by itself when the call in flight
              finishes, so the move is to wait, or to fund the key (money is not
              limited this way, and a funded key answers both at once);
            * `operation_limit_reached` — a connector's own ceiling on one
              operation (a technical cap against a loop), with `limit`,
              `window`, `operation` and `retry_after_seconds`;
            * `rate_limit_exceeded` — this key's calls per minute. A request
              stopped earlier, by the per-address limiter, is a bare 429 with no
              `reason`.

            None of them is a quota on how many calls a paying caller may make:
            there is no such quota.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  reason:
                    type: string
                    enum: [call_already_in_flight, operation_limit_reached, rate_limit_exceeded]
                  terminal:
                    type: boolean
                    description: False means waiting clears it; true means it will not.
                  limit:
                    type: integer
                    description: For `operation_limit_reached` — the ceiling that was reached.
                  window:
                    type: string
                    description: For `operation_limit_reached` — the period the ceiling is counted over, e.g. `day`.
                  operation:
                    type: string
                    description: For `operation_limit_reached` — the operation the ceiling is on.
                  retry_after_seconds:
                    type: [integer, 'null']
                    description: For `operation_limit_reached` — how long until the counter expires.
        '401':
          description: >
            No payment credential, or one that cannot pay. `reason` tells the two
            apart: `missing_payment_key` for a caller that sent nothing, and
            `wk_is_not_a_payer` for one that sent a `wk_` — that credential names a
            wallet on /wallet/v1/*, it does not buy anything here.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallRefusal'

  /calls/{call_id}:
    get:
      tags: [Execution]
      operationId: getCallResult
      summary: Poll an asynchronous call
      security:
        - PaymentKeyAuth: []
        - BearerAuth: []
      parameters:
        - name: call_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: The call's current state. `status` is `pending` until it settles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectCallResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No call has this id; `reason` is `call_not_found`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallRefusal'

  # ============================================================================
  # Payment keys and subscriptions
  # ============================================================================
  /wallet/v1/create-payment-key:
    post:
      tags: [Subscriptions]
      operationId: createPaymentKey
      summary: Create a payment key for this wallet
      description: |
        Two transactions on chain: the key's secret is stored, then funded. The
        response carries `payment_key` (`owner:nonce:secret`), shown once — it
        is what `/call` takes as `X-Payment-Key`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentKeyRequest'
      responses:
        '200':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentKeyResponse'
        '400':
          description: The amount is not one an account can hold.
        '402':
          description: |
            The wallet holds less than the deposit asks for. The message names
            what it holds, what is needed, and where to send it.
        '503':
          description: |
            The wallet's balance could not be read, so nothing was attempted and
            nothing was charged. Transient — retry.
        '401':
          $ref: '#/components/responses/Unauthorized'

  /wallet/v1/subscription/purchase-info:
    get:
      tags: [Subscriptions]
      operationId: subscriptionPurchaseInfo
      summary: What is on sale, and what this wallet needs to buy it
      responses:
        '200':
          description: |
            The plans on chain joined with their terms. An empty list means one
            half is missing — a plan is sellable only when both exist.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'

  /subscription/status:
    get:
      tags: [Subscriptions]
      operationId: subscriptionStatus
      summary: A key's allowance, balance, and the connectors in its scope
      security:
        - PaymentKeyAuth: []
      responses:
        '200':
          description: |
            `allowance_*` describe a subscription; `balance` and `withdrawable`
            describe money. A call covered by an allowance costs the caller
            nothing at the moment of the call — and pays the connector's author
            nothing either.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatus'
        '401':
          description: |
            No `X-Payment-Key`. The report is on one payment key, so that key is
            what is presented — a `wk_` alone does not name one. A wallet gets a
            key from `POST /trial-key` or `POST /wallet/v1/create-payment-key`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /subscription/purchase:
    post:
      tags: [Subscriptions]
      operationId: purchaseAllowance
      summary: Turn balance already on a key into allowance
      description: |
        Buys a plan out of the key's own balance. The same plan can be bought
        on chain for any payment key, with an `ft_transfer_call` carrying
        `{"action":"buy_subscription","nonce":N,"owner":"<key owner>","plan":0}`.

        Never on the wallet's trial key (nonce 0): the contract keeps no record
        there, and its subscription is OutLayer's to give. That key is answered
        `400` with `reason: trial_key_not_purchasable`; buy on a payment key
        the wallet creates (nonce ≥ 1).

        Never with a grant: a key OutLayer funded (`is_grant`) pays for calls
        only, and a subscription on it is OutLayer's to give. That key is
        answered `403` with `reason: grant_key_not_purchasable`; buy on a
        payment key you funded yourself.

        Only the plan's PRICE is spent; an overpayment stays on the key as
        balance. The allowance ADDS to whatever is there and validity extends
        from `max(now, expires_at)`, so buying again never shortens what is
        already paid for.

        A `wk_` is deliberately NOT accepted here: it runs a wallet and does not
        spend a payment key's balance.
      security:
        - PaymentKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount_usd]
              properties:
                amount_usd:
                  type: string
                  description: |
                    Stablecoin minimal units, as an integer string. `10000000`
                    is $10.00.
                plan:
                  type: integer
                  description: |
                    Which plan, by index — the same identifier an on-chain
                    purchase names. Absent means the cheapest on sale. A payment
                    short of the named plan buys the best plan it does cover.
      responses:
        '200':
          description: The plan sold, which is not always the one asked for.
          content:
            application/json:
              schema:
                type: object
                properties:
                  plan: { type: string }
                  allowance_purchased_usd: { type: string }
                  allowance_total_usd: { type: string }
                  spent_usd:
                    type: string
                    description: The PLAN'S price, not the whole `amount_usd`.
                  expires_at: { type: string }
                  days_added: { type: integer }
        '402':
          description: The key's balance does not cover the cheapest plan on sale.
        '400':
          description: |
            `reason: invalid_request` — `amount_usd` is not a positive integer,
            or buys no plan on sale (the message names the cheapest); or
            `reason: trial_key_not_purchasable` — the key presented is the
            wallet's trial key (nonce 0). **`terminal: true`**.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallRefusal'
        '403':
          description: |
            `reason: grant_key_not_purchasable` — the key holds a grant from
            OutLayer, which pays for calls and does not buy a plan.
            **`terminal: true`**.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallRefusal'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /subscription/notifications:
    put:
      tags: [Subscriptions]
      operationId: setSubscriptionNotifications
      summary: Where to warn the owner about the allowance and the expiry
      description: |
        Either channel, or both; `null` clears one. Never defaulted to an
        address the owner did not choose — a warning nobody reads is worse than
        no warning.

        PERSONAL DATA: the address is stored against the key.
      security:
        - PaymentKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email: { type: [string, 'null'] }
                webhook_url: { type: [string, 'null'] }
      responses:
        '200':
          description: What is stored now.
          content:
            application/json:
              schema:
                type: object
                properties:
                  email: { type: [string, 'null'] }
                  webhook_url: { type: [string, 'null'] }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /trial-key:
    post:
      tags: [Subscriptions]
      operationId: claimTrialKey
      summary: Claim this wallet's trial — fifty connector calls in its first week
      description: |
        **A trial is fifty connector calls, within seven days of the wallet's
        creation.** That is all of it. The answer is a payment key, sent as
        `X-Payment-Key` like any other, plus how many calls it makes and when it
        stops working.

        * The week is counted from the WALLET's creation, not from the claim: a
          trial claimed on day six works for one day. Claim it when you register.
        * A call counts once it is accepted and queued, whatever becomes of it
          afterwards — a run that fails or times out is still one of the ten. A
          refused attempt costs nothing.
        * The eleventh call answers `402 trial_exhausted`, and any call after the
          week `402 trial_expired` — both `terminal: true`. The next step is a
          payment key with money on it (`POST /wallet/v1/create-payment-key`),
          and **a funded key has no call limit at all**.
        * It reaches the curated connectors and nothing else; any other project
          is refused as `project_not_allowed`. It cannot pay a developer through
          `X-Attached-Deposit` and cannot be withdrawn.
        * `GET /subscription/status` with the key reports
          `trial: { calls, calls_used, calls_left }`. There is no balance to
          read: a trial is not measured in money.

        One per wallet. Any wallet credential claims it: `Bearer wk_…` or
        `Bearer near:…`.

        **The key is derived, not drawn at random**, so the wallet reads it
        again at any time with `GET /wallet/v1/payment-key` under the same
        credential. A client that derives its wallets from a NEAR account and
        a seed stores nothing.
      security:
        - BearerAuth: []
      responses:
        '200':
          description: The claimed key and what it is good for.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialKeyResponse'
        '401':
          description: "No wallet credential, or one that is unknown, revoked or wrongly signed — the wallet API's own answer."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: "`trial_window_closed` — the wallet is past its first week. `trial_unavailable` — no trial is offered to this caller. Both terminal: the way forward is a funded payment key."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialKeyRefusal'
        '404':
          description: "`trial_disabled` — this deployment offers no trial."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialKeyRefusal'
        '409':
          description: "`trial_already_claimed` — this wallet has had its one; read it again with `GET /wallet/v1/payment-key`. Terminal."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialKeyRefusal'
        '503':
          description: "`internal_error` — the key could not be issued right now. `terminal: false`: the same request works later."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialKeyRefusal'

  /wallet/v1/payment-key:
    get:
      tags: [Subscriptions]
      operationId: getPaymentKey
      summary: Read this wallet's nonce-0 key again
      description: |
        The key `POST /trial-key` or `POST /wallet/v1/sponsorship` issued, as
        the same string, as many times as asked. The key is derived from the
        wallet's master in the keystore and bound to the credential that
        claimed it (`Bearer wk_…`, or `Bearer near:…`): only that credential
        reads it, and the key works only while that `wk_` is live. A client that derives its
        wallets from a NEAR account and a seed therefore stores no key at all
        and re-reads it after a restart.

        `subscription` is true once the key carries a subscription — an
        operator's gift or a sponsor code's grant — rather than the bare trial;
        `GET /subscription/status` with the key has the figures.
      security:
        - BearerAuth: []
      responses:
        '200':
          description: The key and its term.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentKeyResponse'
        '401':
          description: "No wallet credential, or one that is unknown, revoked or wrongly signed — the wallet API's own answer."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: "`payment_key_other_credential` — the key was claimed with another credential of this wallet; only that one reads it."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialKeyRefusal'
        '404':
          description: "`no_payment_key` — this wallet has no nonce-0 key yet: claim the trial or redeem a sponsor code."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialKeyRefusal'
        '409':
          description: "`payment_key_not_recoverable` — the key was issued at random before keys were derived; it was shown once. A sponsor code redeem that sends it as `X-Payment-Key` moves the slot to a derived key this route reads. `payment_key_revoked` — the `wk_` it was claimed with is revoked, and the key with it. Otherwise create a payment key."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialKeyRefusal'
        '503':
          description: "`internal_error` — `terminal: false`: the same request works later."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialKeyRefusal'

  /wallet/v1/sponsorship:
    post:
      tags: [Subscriptions]
      operationId: redeemSponsorCode
      summary: Redeem a sponsor code — a subscription on this wallet's nonce-0 key, paid by the sponsor
      description: |
        A sponsor code, `spn_…`, is a secret somebody gave you: a friend's
        one-time link, a voucher posted in public, or the backend that runs you.
        Redeeming it puts the code's allowance on your wallet's nonce-0 key for
        the code's term — the trial's key if you claimed one, a new key if not —
        and converts the trial: no call count from then on. The key then pays
        for connector calls exactly as a bought subscription does.

        Any wallet credential: `Bearer wk_…` or `Bearer near:…`. The trial's
        claim window does not apply; the code is the gate. A key carries one
        sponsor while its grant is live: the same code again, or another code
        before the grant ends, changes nothing and answers what the key holds.
        After the grant ends, another code is taken. A code this wallet
        redeemed once is never taken again, and a code that is one per address
        is never taken again from an address it was redeemed from, whatever
        the key carried in between.

        A code that cannot be redeemed answers `404 sponsor_code_invalid`,
        whatever the reason. Ask the person who gave it to you. Only the
        credential that reads the wallet's nonce-0 key redeems onto it — the
        same rule as `GET /wallet/v1/payment-key` — with one exception: a key
        issued at random, before keys were derived, is bound to the caller
        first when the request sends that key as `X-Payment-Key`. Holding it
        is the proof; the slot moves to the derived key, which the answer
        carries and `GET /wallet/v1/payment-key` reads from then on. A refused
        redeem takes no use of the code and changes no binding.

        A sponsor code's subscription pays for connector calls. It leaves the
        wallet under the free tier's custody limits unless the sponsor set
        the code up to lift them.
      security:
        - BearerAuth: []
      parameters:
        - name: X-Payment-Key
          in: header
          required: false
          schema: { type: string }
          description: The wallet's nonce-0 key, `{owner}:0:{key}`, when it was issued at random and cannot be read again — the proof that binds it to this credential. Not needed otherwise.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code]
              properties:
                code:
                  type: string
                  description: The code as given, `spn_…`.
      responses:
        '200':
          description: The key, now carrying the sponsor's subscription — or, when the key already carries a live sponsor, as it already was.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SponsorshipResponse'
        '401':
          description: "No wallet credential, or one that is unknown, revoked or wrongly signed — the wallet API's own answer."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: "`payment_key_other_credential` — the wallet's nonce-0 key was claimed with another of its credentials; redeem with that one."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialKeyRefusal'
        '404':
          description: "`sponsor_code_invalid` — the code cannot be redeemed by this wallet now. Terminal; nothing more is said."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialKeyRefusal'
        '409':
          description: "`sponsor_cannot_top_up` — the key can already spend more than this code gives; a sponsorship tops up and never takes away. `payment_key_deleted` — the wallet's nonce-0 key was deleted and the slot cannot be used again. `payment_key_not_recoverable` — the wallet's nonce-0 key was drawn at random and the request did not send it as `X-Payment-Key`. `payment_key_revoked` — the `wk_` the key was claimed with is revoked, and the key with it."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialKeyRefusal'
        '503':
          description: "`internal_error` — `terminal: false`: the same request works later."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialKeyRefusal'

  /public/connectors:
    get:
      tags: [Connectors]
      operationId: publicConnectors
      summary: Which connectors this deployment offers, and where to read about each
      description: |
        The list comes from the same on-chain price table a call is priced by,
        so a connector named here can be called and one absent here would be
        refused.

        What each connector SELLS is not repeated here. Its operations and their
        prices are on chain, and the connector's own free `status` answers with
        them — as does a refusal, which lists what could have been asked for.

        `description` and `skill` are present for the curated connectors; the
        test probes are documented in a README beside their code.
      security: []
      responses:
        '200':
          description: The connectors of this deployment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  network: { type: string, enum: [mainnet, testnet] }
                  connectors_account: { type: string }
                  docs: { type: string }
                  how_to_call: { type: string }
                  library_skill: { type: string }
                  connectors:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        project_id: { type: string }
                        description: { type: string }
                        skill: { type: string }
  /public/connectors/{id}/describe:
    get:
      tags: [Connectors]
      operationId: publicConnectorDescribe
      summary: What a connector does and takes, from the wasm that is deployed
      description: |
        The `describe` block of the `outlayer.manifest` section in the
        connector's ACTIVE version — the bytes the workers run, covered by the
        hash the contract records. The operations come back as a list in the
        manifest's order, each with its class, one sentence, and the parameters
        it reads. No prices: those are on chain and in the connector's `status`.

        This is what `app.outlayer.ai/connectors/{id}` renders. The connector's
        build holds the block to its code, so a description that fell behind
        the code could not have been published.
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
          example: gmail
      responses:
        '200':
          description: The connector, described by its own manifest.
          content:
            application/json:
              schema:
                type: object
                properties:
                  connector_id: { type: string }
                  project_id: { type: string }
                  network: { type: string, enum: [mainnet, testnet] }
                  version: { type: string, description: The active version's wasm hash. }
                  display: { type: object }
                  summary: { type: string }
                  operations:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string }
                        class: { type: string, enum: [read, write] }
                        doc: { type: string }
                        params:
                          type: array
                          items:
                            type: object
                            properties:
                              name: { type: string }
                              type: { type: string, description: "Prose for a developer, not a schema language." }
                              required: { type: boolean }
                              doc: { type: string }
                  limits: { type: array, items: { type: object } }
                  callers:
                    type: [object, 'null']
                    description: |
                      The manifest's `callers` block as written: which doors a
                      run may come through (`direct`, `contract`, `https`,
                      `meta_tx`). `null` when the manifest declares none, which
                      admits every door. A door the block leaves out is
                      `allow`, except `meta_tx`, which is `deny`.
                    properties:
                      direct: { type: string, enum: [allow, deny] }
                      contract:
                        oneOf:
                          - { type: string, enum: [allow, deny] }
                          - type: object
                            required: [only]
                            properties:
                              only: { type: array, items: { type: string }, minItems: 1, maxItems: 32 }
                      https: { type: string, enum: [allow, deny] }
                      meta_tx: { type: string, enum: [allow, deny] }
        '404':
          description: No such connector on this network, not published, or a version without a `describe` block.
        '503':
          description: The contract could not be read.
  /payment-keys/balance:
    get:
      tags: [Subscriptions]
      operationId: paymentKeyBalance
      summary: What is left on the key presented
      description: |
        The key reports on itself. Money is `available`; a subscriber also gets
        the two allowance figures; a TRIAL key gets `trial` instead of them —
        a trial is a number of calls and has no balance to read.
      security:
        - PaymentKeyAuth: []
      responses:
        '200':
          description: The key's money, and its allowance or trial when it has one.
          content:
            application/json:
              schema:
                type: object
                properties:
                  owner: { type: string }
                  nonce: { type: integer }
                  initial_balance: { type: string }
                  spent: { type: string }
                  reserved: { type: string }
                  available: { type: string, description: "Money only, in minimal stablecoin units." }
                  last_used_at: { type: [string, 'null'] }
                  is_grant: { type: boolean, description: "The value on the key was given, not paid in: it cannot be withdrawn or attached as a deposit." }
                  expires_at: { type: string, description: When an allowance or a trial ends. Absent without one. }
                  trial:
                    type: object
                    description: A trial key only. The allowance figures are then absent.
                    properties:
                      calls: { type: integer }
                      calls_used: { type: integer }
                      calls_left: { type: integer }
                  allowance_usd: { type: string, description: Subscribers only. }
                  allowance_available_usd: { type: string, description: "Subscribers only — what is left, counting expiry." }
                  withdrawable: { type: string }
        '401':
          description: No `X-Payment-Key`, or one that does not match a key.

  /public/payment-keys/{owner}/{nonce}/balance:
    get:
      tags: [Subscriptions]
      operationId: publicPaymentKeyBalance
      summary: What a key has spent and what is left, without presenting it
      description: |
        Addressed by owner and nonce rather than by the key itself, so a
        dashboard can show a key's balance without holding its string. It
        reports MONEY only — allowance and expiry need the key, through
        `/subscription/status`.
      security: []
      parameters:
        - name: owner
          in: path
          required: true
          schema: { type: string }
        - name: nonce
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Money on the key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  owner: { type: string }
                  nonce: { type: integer }
                  initial_balance: { type: string }
                  spent: { type: string }
                  reserved: { type: string }
                  available: { type: string }
                  last_used_at: { type: [string, 'null'] }
        '404':
          description: No such key.

  # ============================================================================
  # A secret left for an agent
  # ============================================================================
  /wallet/v1/agent-secret/pubkey:
    get:
      tags: [Subscriptions]
      operationId: agentSecretPubkey
      summary: The key to seal a secret for this agent
      description: |
        Encrypt on your own machine and send back only ciphertext — the
        credential never exists in this process. The answer names the seed and
        the agent so a mismatch is visible rather than silent.

        Give exactly ONE of `project_id` and `wasm_hash`. A project secret is
        readable by every version of that project; a `wasm_hash` secret is
        readable only by that exact build, and a rebuild that changes a byte
        cannot open it. They seal to different seeds, so the choice made here
        must be the one made when storing.
      parameters:
        - name: project_id
          in: query
          required: false
          schema: { type: string }
        - name: wasm_hash
          in: query
          required: false
          schema: { type: string }
      responses:
        '200':
          description: X25519 public key (hex), encrypt-only.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSecretPubkey'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /wallet/v1/agent-secret:
    post:
      tags: [Subscriptions]
      operationId: storeAgentSecret
      summary: Store a secret for this agent, the agent's wallet paying
      description: |
        The agent's own wallet signs and stakes the storage, so it needs about
        0.11 NEAR. With none, the answer says so and names the endpoint that
        pays instead.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [encrypted_secrets_base64]
              properties:
                project_id:
                  type: string
                  description: Exactly one of this and `wasm_hash`.
                wasm_hash:
                  type: string
                  description: One exact build instead of a project.
                encrypted_secrets_base64:
                  type: string
                  description: Sealed to the key from `/agent-secret/pubkey`. Never a plaintext secret.
      responses:
        '200':
          description: Stored.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tx_hash: { type: string }
                  agent_account: { type: string }
        '402':
          description: The agent's wallet cannot pay the storage deposit.
        '401':
          $ref: '#/components/responses/Unauthorized'

  /wallet/v1/agent-secret/prepare:
    post:
      tags: [Subscriptions]
      operationId: prepareAgentSecret
      summary: The same store, as a call for the payer to send
      description: |
        The keystore only signs; the call comes back for `payer` to send from
        their own account, so the agent's wallet needs no NEAR at all. The
        signature binds every argument that decides what is stored, who may read
        it and who pays — including the payer, so handing the prepared call to
        somebody else is a refusal rather than a shortcut.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [encrypted_secrets_base64, payer]
              properties:
                project_id:
                  type: string
                  description: Exactly one of this and `wasm_hash`.
                wasm_hash:
                  type: string
                  description: One exact build instead of a project.
                encrypted_secrets_base64: { type: string }
                payer:
                  type: string
                  description: The account that will send the transaction and stake the storage.
      responses:
        '200':
          description: A `store_agent_secret` call, complete with the wallet's signature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreparedAgentSecret'
        '503':
          description: |
            The ciphertext did not decrypt under this agent's seed, so nothing
            was signed. Encrypt with the key from `/agent-secret/pubkey` for
            this exact project.
        '401':
          $ref: '#/components/responses/Unauthorized'

  /wallet/v1/agent-secret/delete/prepare:
    post:
      tags: [Subscriptions]
      operationId: prepareAgentSecretDelete
      summary: Remove the agent's secret, as a call for the payer to send
      description: |
        The mirror of `/agent-secret/prepare`: the keystore signs, `payer` sends
        the call from their own account, and the storage deposit goes back to
        whoever sends it. The agent needs no NEAR to be forgotten.

        Authority is the `wk_`, not the NEAR account paying. The agent's key
        never moves — it IS the agent's account — so a rotated credential still
        speaks for the agent, and a wallet whose seed is lost cannot delete its
        secrets at all.

        Signed under its OWN domain, so a signature obtained to store a secret
        cannot be presented to destroy one.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [payer]
              properties:
                project_id:
                  type: string
                  description: Exactly one of this and `wasm_hash`.
                wasm_hash:
                  type: string
                  description: One exact build instead of a project.
                payer:
                  type: string
                  description: |
                    The account that will send the transaction, and the one the
                    storage deposit returns to.
      responses:
        '200':
          description: |
            A `delete_agent_secret` call, complete with the wallet's signature.
            No deposit field: the method is not payable, and attaching anything
            is refused before the contract sees it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreparedAgentSecretDelete'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

# ==============================================================================
# Components
# ==============================================================================
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: wk_<32-hex-chars>
      description: |
        API key returned by `POST /register`. Format `wk_<hex>`. Pass as
        `Authorization: Bearer wk_...`. Every route that takes it also takes a
        deterministic wallet's `Bearer near:<base64url>` token (see
        `POST /register` and `authSign`).
    OwnerSession:
      type: http
      scheme: bearer
      bearerFormat: os_<64-hex-chars>
      description: |
        An owner's session on one device, opened by `POST /inbox/session` with
        a statement the owner's wallet signed. Pass as
        `Authorization: Bearer os_...`. It ends at the statement's deadline,
        30 days at most, and is not extended: a new statement opens a new one,
        beside the ones in force. A session also ends when the key that signed
        it is removed from the account, or stops being a full-access key: the
        chain is asked on a timer, and its answer ends a session when it is
        given twice.
    PaymentKeyAuth:
      type: apiKey
      in: header
      name: X-Payment-Key
      description: |
        A payment key, `{owner}:{nonce}:{secret}`. Created by
        `POST /wallet/v1/create-payment-key` and funded on chain, claimed as a
        trial with `POST /trial-key`, or granted by a sponsor code with
        `POST /wallet/v1/sponsorship`; the nonce-0 key is read again with
        `GET /wallet/v1/payment-key`. A wallet's `Authorization: Bearer wk_...`
        does not stand in for it: on `/call` it is refused as `wk_is_not_a_payer`.

  parameters:
    TaskId:
      name: id
      in: path
      required: true
      description: A task's id — 1 to 80 of `a-z`, `0-9` and `-`.
      schema:
        type: string
        pattern: '^[a-z0-9-]{1,80}$'
    IdempotencyKey:
      name: X-Idempotency-Key
      in: header
      required: false
      schema:
        type: string
      description: |
        One key per operation, scoped to `(wallet, key)`; the request body is
        never compared. The key is written on the request row BEFORE any funds
        move, so a key seen again names the request that reserved it, whatever
        became of it, and nothing runs twice.

        A seen key answers **HTTP `200`** with `error: duplicate_idempotency_key`
        and the request it belongs to:
        ```json
        {"error": "duplicate_idempotency_key",
         "message": "Request already processed: <request_id>",
         "request_id": "<request_id>", "type": "withdraw", "status": "processing",
         "result": {...}, "poll_url": "/wallet/v1/requests/<request_id>",
         "created_at": "...", "updated_at": "..."}
        ```
        `status` is the request's as recorded; `poll_url` is present while it is
        not terminal (`success`/`completed`, `failed`, `refunded`,
        `needs_review`); `result` and `updated_at` once the row has them.
        Because the HTTP code is `200`, branch on `error` in the body.

        For `createPaymentCheck` and `batchCreatePaymentChecks` the body also
        carries `checks`: `[{check_id, check_key, status}]` — the checks that
        key made, each with its key derived again for the API key that asks.
        A caller that lost the create's answer gets its only copy back here.
        `check_key` is `null` when the asking API key is not the one the check
        was created with (a key of the same wallet under another vault derives
        a different key): re-send with the key that created it. A batch lists
        the checks reserved so far while its request is `processing`, and all
        of them once it is `completed`.
        If the re-derivation cannot be done (the keystore does not answer), the
        re-send is refused like any keystore call and can be sent again.

        A key is held by the request that reserved it, including one that ended
        `failed` after the reserve. A refusal before the reserve — authentication,
        a malformed body, the policy, `wallet_busy`, a bad `X-Answer-Within` —
        holds nothing, and the same key may be sent again.

        Recovery after a timeout or a dropped connection: re-send with the same
        key and read `request_id` and `status` from whichever answer comes — the
        plain one, this duplicate, or `409 wallet_busy` with `in_flight_request_id`
        (`null` while the request is being written: retry in a moment). With no
        header the server mints a fresh key per call, so nothing is deduplicated.
    AnswerWithin:
      name: X-Answer-Within
      in: header
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 80
      description: |
        How many seconds after the request arrives this call waits for the
        operation to settle before it answers `status: processing` with
        `request_id` and `poll_url` (`createPaymentCheck`: `status: creating`
        with the check's `poll_url`). Whole seconds, `0` to `80`; `0` answers as
        soon as the funds are handed over. Absent, the call waits its own
        budget: up to 80 s, and the relay's 60 s on a same-chain transfer or
        withdraw. The wait only shortens: the operation itself runs to its
        outcome and settles the request whatever the client waited. Two things
        it does not cut: the hand-over itself (one relay publish, up to 30 s),
        and in `batchCreatePaymentChecks` the hand-over of every check, which
        the wait follows. A value outside the range is refused
        `400 bad_request` before anything runs, and reserves nothing. Set it a
        few seconds below your client's timeout, so a slow settlement answers
        with an id to poll instead of a dropped connection. The header is read
        on every wallet route: it acts on the operations that wait (the ones
        that list it), and is accepted and changes nothing elsewhere.

  responses:
    InboxRefused:
      description: The inbox refused; branch on `reason`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InboxRefusal'
    InboxUnavailable:
      description: The database or the chain did not answer
      headers:
        Retry-After:
          schema: { type: integer }
          description: Seconds until the same request is worth repeating.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InboxRefusal'
    InboxTooManyRequests:
      description: Too many requests
      content:
        text/plain:
          schema:
            type: string
            example: Too many requests. Try again later.
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            bad_request:
              value: { error: bad_request, message: "amount must be positive" }
            invalid_address:
              value: { error: invalid_address }
            unsupported_chain:
              value: { error: unsupported_chain, message: "Unsupported chain: 'nosuchchain' is not a chain 1Click serves; the catalog lists: abs, adi, aleo, …" }
            unsupported_token:
              value: { error: unsupported_token }
            no_liquidity:
              value: { error: no_liquidity, message: "No liquidity available" }
            upstream_rejected:
              value: { error: upstream_rejected, message: "Amount is too low for bridge, try at least 30368" }
            insufficient_balance:
              value: { error: insufficient_balance }
    Unauthorized:
      description: Missing or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_auth:
              value: { error: missing_auth }
            invalid_api_key:
              value: { error: invalid_api_key }
            timestamp_expired:
              value: { error: timestamp_expired }
    Forbidden:
      description: Action blocked by policy or wallet state
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            policy_denied:
              value: { error: policy_denied, message: "daily limit exceeded" }
            wallet_frozen:
              value: { error: wallet_frozen }
            not_approver:
              value: { error: not_approver }
    NotFound:
      description: Resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            request_not_found:
              value: { error: request_not_found }
            approval_not_found:
              value: { error: approval_not_found }
    RateLimited:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rate_limited:
              value: { error: rate_limited }
    OperationLimitReached:
      description: >-
        The wallet's counted ceiling on this custody operation is reached
        (`operation_limit_reached`): the free tier allows 1000 `custody:*`
        operations per wallet per rolling 24 h, dry-runs, swap quotes and
        NEP-413/EVM/Solana signing included; reads are not counted. The
        body says the ceiling, its window and when the counter clears;
        `Retry-After` carries the same seconds when they are known. Wait it
        out, or lift the ceiling with a subscription on the wallet's own key.
      headers:
        Retry-After:
          description: Seconds until the counter that refused this clears. Absent when unknown.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperationLimitReachedResponse'
    RouteUnavailable:
      description: >-
        Nothing is known about the route: 1Click did not answer
        (`route_unavailable` — a 5xx, a timeout, "Failed to get quote"), the
        chain or its token catalog could not be read (`chain_unavailable`), or
        the keystore was unreachable (`keystore_error`). Transient — retry
        after `Retry-After`. On a testnet deployment NEAR Intents routes answer
        `service_unavailable` instead, which does not clear.
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            route_unavailable:
              value: { error: route_unavailable, message: "1Click could not answer for this route: Failed to get quote" }
            chain_unavailable:
              value: { error: chain_unavailable }
    InternalError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_error:
              value: { error: internal_error }
    ServiceUnavailable:
      description: >-
        Unavailable — either permanently on this deployment or transiently, and
        the code says which. `service_unavailable`: feature not
        enabled/configured (e.g. the `/wallet/v1/confidential/*` routes when
        `ENABLE_CONFIDENTIAL_INTENTS` is off, the binding-event endpoints
        without a webhook secret, or NEAR Intents on a network with no solvers)
        — do not retry; no interval is sent because none would be true.
        `chain_unavailable`: the chain, or a node in front of it, could not
        answer this second — a balance that could not be read, a code hash that
        could not be fetched, a binding that could not be verified, a
        transaction that expired against a block the node has forgotten.
        Nothing happened and nothing was charged — transient, retry after the
        `Retry-After` header. `keystore_error`: the TEE keystore (signing / key
        derivation) was unreachable or rejected the request — transient, retry
        after `Retry-After`. `upstream_unavailable`: this deployment's database
        could not serve the request right now — transient, retry after
        `Retry-After`; the same code `/call` answers the condition with.
        `confidential_jwt_expired`: the confidential
        per-account JWT was rejected by the 1Click upstream and
        re-authentication also failed — transient, retry after `Retry-After`.
        `route_unavailable`: 1Click did not answer for the route (a 5xx, a
        timeout, "Failed to get quote") — transient, retry after `Retry-After`;
        nothing is known about the route.
        (Transient upstream failures use 503 rather than 502 because
        Cloudflare replaces origin 502/504 responses with its own HTML error
        page, hiding the JSON body from clients.)
      headers:
        Retry-After:
          description: >-
            Present on transient failures (`chain_unavailable`,
            `keystore_error`, `upstream_unavailable`, `confidential_jwt_expired`) — seconds to wait
            before retrying. Absent on `service_unavailable`, which is not
            transient: there is no interval after which an unset environment
            variable becomes set.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            service_unavailable:
              value:
                error: service_unavailable
                message: Confidential intents are not configured on this deployment
            keystore_error:
              value: { error: keystore_error }
            confidential_jwt_expired:
              value: { error: confidential_jwt_expired }
    OnChainTxFailed:
      description: >-
        The transaction was signed and broadcast — the network accepted it —
        but its on-chain execution REVERTED. `tx_hash` is real (the tx is on
        chain); no state-changing effect happened. Do NOT retry:
        re-broadcasting duplicates an already-recorded transaction and burns
        gas again. `message` is the decoded FunctionCallError / panic string,
        `failure` the raw NEAR execution-failure JSON. (422 rather than 502
        because Cloudflare replaces origin 502/504 responses with its own HTML
        error page, which would hide this body from clients.)
        Scope: synchronous execution only. When the operation goes through the
        multisig approval flow instead, execution happens in the background
        after the threshold is met — a revert there surfaces as
        `status: "failed"` via `GET /wallet/v1/requests/{request_id}` and the
        `request_completed` webhook, never as a synchronous 422.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OnChainTxFailedError'
          examples:
            onchain_tx_failed:
              value:
                error: onchain_tx_failed
                message: 'Exceeded the prepaid gas.'
                tx_hash: 8YyQnDxNSgrtZtAhDwHRfcpyTAcqGJ4kdmSf7eVLh2dG
                failure:
                  ActionError:
                    index: 0
                    kind:
                      FunctionCallError:
                        ExecutionError: 'Exceeded the prepaid gas.'

  schemas:
    # ----- Execution -----
    ProjectCallRequest:
      type: object
      required: [input]
      properties:
        input:
          type: object
          description: |
            The project's own input. A CONNECTOR additionally requires a
            top-level `operation` string here — the one field every connector
            uses, read by the contract, the coordinator, the worker and the
            guest alike.
          properties:
            operation:
              type: string
              description: Required for connectors. `op` is not accepted.
        async:
          type: boolean
          default: false
          description: |
            Return at once with `call_id` and `poll_url` instead of holding the
            connection. No window applies on this path — long work belongs here.
        version_key:
          type: string
          pattern: '^[A-Za-z0-9._-]{1,128}$'
          description: |
            Pin a specific published version instead of the active one.
            Refused with `invalid_version_key` (400) on a connector project:
            connectors run their active version only, since an older version
            would run an older manifest and older code under the curated name.
        use_bound_identity:
          type: boolean
          default: false
          description: |
            Agent Connect: run under the BOUND asset account's name, so the
            guest's `NEAR_SENDER_ID` becomes e.g. `agent.tla` instead of the
            wallet's own account. near-email turns that into the mailbox it
            sends from, and other connectors derive keys and state from it.

            Opt-in, and off by default on purpose. A binding is a capability
            the agent gains, not a change to who it already is — renaming the
            guest the moment one activated would move every derived identity
            with nothing in your code to point at.

            Requires an ACTIVE binding, and says so rather than falling back:
            with no binding — or with one still pending, or revoked — the call
            is refused `409 no_bound_identity` before it is priced or charged.
            The worker then re-verifies the claim against the chain inside the
            TEE and refuses the job if the chain disagrees. Billing never
            follows the name: `NEAR_USER_ACCOUNT_ID` stays the paying key's
            owner.
        secrets_ref:
          type: object
          description: |
            The stored secret this run reads: the row `account_id` stored for
            this project under `profile`, decrypted inside the TEE only if the
            row's on-chain access condition admits the paying key's owner. On a
            connector project a body reference is used as it is; without one,
            `X-Use-Owner-Secret` names the wallet's own row.
            On a trading connector (`hyperliquid`, `polymarket`) of a wallet
            that has an owner, the policy is the OWNER's: with no reference the
            owner's row `{owner, <connector>}` is attached, a row of the owner's
            is kept, and any other account's is refused with
            `403 policy_row_not_owner`; doing that repeatedly answers
            `403 calls_suspended` to the wallet's calls for a while
            (`terminal: false` — the same call succeeds once it ends). A row
            the call names under a profile other than the connector's own that
            is not stored is refused in the run's result (`policy_row_missing`),
            never run with no policy. A profile per wallet caps that wallet only
            while `{owner, <connector>}` exists too: a call that names no row
            runs that one, and with none stored, the connector's built-in
            default.
            Refused with `invalid_secrets_ref` (400) when `account_id` is not a
            NEAR account id or `profile` is not 1–64 bytes or holds an ASCII
            character other than a letter, digit, `-` or `_`: the contract
            stores no such row, so nothing is queued for it. A body whose
            fields are not strings is rejected as a body-shape error (422)
            before this check.
          properties:
            profile: { type: string }
            account_id: { type: string }
    ProjectCallResponse:
      type: object
      properties:
        call_id: { type: string, format: uuid }
        status:
          type: string
          enum: [pending, completed, failed]
        output: { type: [object, 'null'] }
        error: { type: [string, 'null'] }
        compute_cost:
          type: [string, 'null']
          description: Stablecoin minimal units, compute only — the operation's fee is separate.
        instructions: { type: [integer, 'null'] }
        time_ms: { type: [integer, 'null'] }
        poll_url:
          type: [string, 'null']
          description: >
            Present while the call is `pending`: an `async` call, or a synchronous one the
            API restarted during. `GET` it until `status` is `completed` or `failed`.
        attestation_url:
          type: [string, 'null']
          description: The TEE quote for this execution.
    InboxRefusal:
      type: object
      description: >
        Every refusal of the inbox. `error` is a sentence written for a person
        and is reworded freely; `reason` is the contract — branch on it. A
        value outside the enum means the client is older than the server: it
        is not a success and not an empty inbox.
      required: [error, reason, terminal]
      properties:
        error: { type: string, description: The human sentence. }
        reason:
          type: string
          description: "`confirmation_required` (403): the action takes the owner's signature, and the request carries none that holds."
          enum: [session_required, session_replaced, invalid_statement, task_not_found, task_closed, task_ending, invalid_request, confirmation_required, upstream_unavailable, internal_error]
        terminal:
          type: boolean
          description: "`true`: the same request can never succeed. `false` on `session_required` and `session_replaced` (sign in) and `upstream_unavailable` (come back)."
        state:
          $ref: '#/components/schemas/TaskState'
    TaskState:
      type: string
      description: >
        `open` waits for the owner. `approved`: the owner signed, and the run
        named in `run` — a run of the agent that prepared the task, on the
        agent's own payment key — is started and has not yet taken the task.
        `answering`: that run took it and acts. `done`: it ended well and the
        project reported. `failed`: it ended any other way — its status is the
        ordinary status of a call — or the task failed before the run acted,
        and `failure_reason` says why. A task never returns to `open`.
      enum: [open, approved, answering, done, failed, rejected, cancelled, expired, void]
    TaskKind:
      type: string
      description: "`confirm` — yes or no; `input` — the owner supplies something; `notice` — tells the owner something and asks nothing: no operation answers it, no reply key, no run follows it, and Got it closes it."
      enum: [confirm, input, notice]
    InboxTask:
      type: object
      required: [id, project_id, project_uuid, preparer, profile, vault, kind, state, created_at, expires_at, reply_pubkey, content, device_copy, locked]
      properties:
        id: { type: string }
        project_id: { type: string, description: "The project whose run made the task, and whose operation answers it." }
        project_uuid: { type: string }
        preparer: { type: string, description: The account whose run made the task. }
        profile: { type: string, description: "The profile of the owner's secret row the task was made for: what the owner's call names in `secrets_ref`." }
        vault:
          type: [string, 'null']
          description: "The vault that row is bound to, whose master seals the task; `null` for the default master."
        kind:
          $ref: '#/components/schemas/TaskKind'
        state:
          $ref: '#/components/schemas/TaskState'
        created_at: { type: integer, description: Unix seconds. }
        expires_at: { type: integer, description: Unix seconds. }
        run: { type: string, description: "The call that acts, or acted, on the owner's approval: a run of the task's preparer, started by the platform." }
        failure_reason:
          $ref: '#/components/schemas/TaskFailureReason'
        reply_pubkey: { type: [string, 'null'], description: "`p256:` and the uncompressed point in base64url: what the owner's answer, note and reason are encrypted to. `null` for a notice, which takes none." }
        content:
          type: [string, 'null']
          contentEncoding: base64
          description: "The task's envelope under its content key: `0x01 || nonce (12) || AES-256-GCM`, bound to the task's id. Present while the task is `open` or `approved`; `null` once it is closed or being acted on."
        device_copy:
          type: [string, 'null']
          contentEncoding: base64
          description: "The content key encrypted to this session's device. `null` when the device has none."
        locked:
          type: boolean
          description: An open task this device has no copy of. It opens after one call of the project's `tasks_unlock` by the owner.
    TaskFailureReason:
      type: string
      description: >
        Why a task is `failed`. Before its run acted: `preparer_key_unavailable`:
        the payment key that prepared the task could not pay for the run
        (deleted, out of funds, spent, expiring, or no longer reaching the
        project). `operation_priced`: the answering operation has a price and
        must be free. `operation_unknown`: the connector sells no such
        operation. `operation_limit_reached`: a limit on the operation is
        reached. `wallet_unresolved`: the key's wallet or its bound identity is
        not the preparing run's. `build_changed`: the connector published a new
        build since the task was made; decided at the approval, before the
        owner's signature is spent, and nothing was charged. `queue_unavailable`:
        the platform could not start the run. `run_not_started`: the run did not take the task in
        time. `run_refused:<reason>`: the run was refused the task by the host
        with `<reason>` (`hash-mismatch`, `not-the-preparer`,
        `approval-invalid`, `expired`, `unavailable`, …) or ended without
        reporting (`unreported`); the agent prepares again on any of these —
        nothing was done. After the run took the task: `run_failed`: the
        project said it did not carry the task out, and `result` holds why;
        `run_trapped`: the project reported the task carried out and then the
        run failed, and `result` holds what it reported — the action most
        likely happened; `run_unreported`: the run ended without a word on the
        task, and it may have acted; `run_unfinished`: no word of the run's end
        in time, and it may have acted. On the last three the agent checks the
        service before it prepares again. Absent in every other state.
      pattern: '^[a-z_]+(:[a-z-]+)?$'
    InboxTaskMoved:
      type: object
      required: [id, state]
      properties:
        id: { type: string }
        state:
          $ref: '#/components/schemas/TaskState'
        run: { type: string, description: "On an approval: the call started for the task's preparer." }
        failure_reason:
          $ref: '#/components/schemas/TaskFailureReason'
    InboxDeleted:
      type: object
      required: [deleted]
      properties:
        deleted: { type: integer }
    InboxMute:
      type: object
      additionalProperties: false
      required: [subject_is, subject]
      properties:
        subject_is: { type: string, enum: [agent, project] }
        subject: { type: string }
    InboxMutes:
      type: object
      required: [mutes]
      properties:
        mutes:
          type: array
          items:
            $ref: '#/components/schemas/InboxMute'
    InboxWebhook:
      type: object
      required: [url, set_at, set_by_key, set_here]
      properties:
        url: { type: [string, 'null'] }
        set_at: { type: [integer, 'null'], description: "When the URL was named, in Unix seconds; `null` with no URL." }
        set_by_key:
          type: [string, 'null']
          description: The wallet key that signed in the session that named the URL; `null` with no URL.
        set_here:
          type: boolean
          description: >
            Whether the URL was named in the session that asks. `false` is a
            URL named in a session that is over, or on another device: one the
            owner should recognise, or remove.
        secret:
          type: string
          description: >
            The secret the owner's events are signed with (`X-Webhook-Signature`
            is the HMAC-SHA256 of the body, in hex). Present only in the answer
            to `PUT`: told once, never again. Naming a URL again makes a new
            secret.
    OwnerSignIn:
      type: object
      additionalProperties: false
      required: [account_id, device_pubkey, valid_until, public_key, signature, nonce]
      properties:
        account_id: { type: string }
        device_pubkey: { type: string, description: "`p256:` and the uncompressed point of the device's public key, base64url without padding." }
        valid_until: { type: integer, description: "Unix seconds; in the future, 30 days at most." }
        public_key: { type: string, description: "The key that signed, `ed25519:<base58>`." }
        signature: { type: string, description: "Base64, 64 bytes; `signature_base64` of `POST /wallet/v1/sign-message`, not its `ed25519:` form." }
        nonce: { type: string, description: "Base64, 32 bytes." }
    OwnerSession:
      type: object
      required: [token, device_id, account_id, valid_until]
      properties:
        token: { type: string, description: "`os_` and 64 hex characters. Returned this once; kept here as its hash." }
        device_id: { type: string, format: uuid }
        account_id: { type: string }
        valid_until: { type: integer }
    OwnerConfirmation:
      type: object
      additionalProperties: false
      required: [at, public_key, signature, nonce]
      description: |
        The owner's signature for one action a session must not do alone:
        withdrawing another device, naming or removing the webhook. NEP-413,
        recipient: the OutLayer contract, a fresh 32-byte nonce, over the
        sentence

            Confirm in OutLayer as {account_id}: {action}. At {at as YYYY-MM-DDTHH:MM:SSZ}.

        where `{action}` is `withdraw the device {id}`, `name the webhook
        {sha256 of the URL, hex}` or `remove the webhook`. The sentence is
        rebuilt from the session's account, the request's action and `at`.
        Good for ten minutes either side of now, once: the nonce is spent.
        The key that signed must be a full-access key of the account.
      properties:
        at: { type: integer, description: "Unix seconds, the moment the sentence names." }
        public_key: { type: string, description: "`ed25519:<base58>`" }
        signature: { type: string, description: "Base64, 64 bytes." }
        nonce: { type: string, description: "Base64, 32 bytes." }
    OwnerDevice:
      type: object
      required: [id, device_pubkey, signer_pubkey, created_at, valid_until, this]
      properties:
        id: { type: string, format: uuid }
        device_pubkey: { type: string }
        signer_pubkey: { type: string, description: The wallet key that signed the device in. }
        created_at: { type: integer }
        valid_until: { type: integer }
        this: { type: boolean, description: The device this session is on. }
    TrialKeyRefusal:
      type: object
      description: >
        Every refusal of the nonce-0 key routes — `POST /trial-key`,
        `GET /wallet/v1/payment-key`, `POST /wallet/v1/sponsorship` — except a
        refused credential, which answers in the wallet API's own shape
        (`ErrorResponse`). Branch on `reason`.
      properties:
        error: { type: string, description: The human sentence. }
        reason:
          type: string
          enum: [unauthorized, trial_disabled, trial_window_closed, trial_already_claimed, trial_unavailable, no_payment_key, payment_key_not_recoverable, payment_key_revoked, payment_key_other_credential, sponsor_code_invalid, sponsor_cannot_top_up, payment_key_deleted, internal_error]
        terminal:
          type: boolean
          description: "`false` only for `internal_error`: the same request works later. Every other refusal is final."
      required: [error, reason, terminal]
    TrialKeyResponse:
      type: object
      required: [payment_key, owner, nonce, calls, expires_at, project_ids]
      properties:
        payment_key:
          type: string
          description: The whole `X-Payment-Key` header value. Read again with `GET /wallet/v1/payment-key`.
        owner: { type: string }
        nonce: { type: integer }
        calls:
          type: integer
          description: How many connector calls this key makes. The whole of a trial's budget.
        expires_at:
          type: string
          format: date-time
          description: When the key stops working, used up or not — the wallet's creation plus the trial's days.
        project_ids:
          type: array
          items: { type: string }
          description: Anything else is refused as `project_not_allowed`.
        note: { type: string }
    PaymentKeyResponse:
      type: object
      required: [payment_key, owner, nonce, subscription]
      properties:
        payment_key:
          type: string
          description: The whole `X-Payment-Key` header value.
        owner: { type: string }
        nonce: { type: integer, enum: [0] }
        expires_at:
          type: [string, 'null']
          format: date-time
        subscription:
          type: boolean
          description: The key carries a live subscription — an operator's gift or a sponsor code's grant that has not ended — rather than the bare trial or an ended grant.
    SponsorshipResponse:
      type: object
      required: [payment_key, owner, nonce, allowance_usd, sponsor, project_ids]
      properties:
        payment_key:
          type: string
          description: The whole `X-Payment-Key` header value.
        owner: { type: string }
        nonce: { type: integer, enum: [0] }
        allowance_usd:
          type: string
          description: The allowance the key carries, minimal units.
        expires_at:
          type: [string, 'null']
          format: date-time
        sponsor:
          type: string
          description: The name of the code the key carries, as its creator set it.
        project_ids:
          type: array
          items: { type: string }
          description: What this key may call — the connectors. Anything else is refused as `project_not_allowed`.
        note: { type: string }
    CallRefusal:
      type: object
      description: >
        Every refusal from `POST /call/{owner}/{project}`. `error` is a sentence
        written for a person and is reworded freely; `reason` is the contract —
        branch on it. The enum is generated from `CallError::reason()` in the
        coordinator and is exhaustive there, so a value outside it means the
        client is older than the server.
      properties:
        error: { type: string, description: The human sentence. }
        terminal:
          type: boolean
          description: >
            Present on the refusals where retrying has an answer. `true` means
            the same request can never succeed; `false` means it succeeds once
            something changes that the caller or the wallet's owner can change.
            `no_bound_identity` sends both: `true` when the paying key names no
            wallet at all, `false` when the wallet simply has no ACTIVE binding
            yet.

            `upstream_unavailable` (503 + `Retry-After`) is this door's
            transient answer — something we depend on has not caught up and the
            same call works later. It is deliberately NOT called
            `service_unavailable`: on `/wallet/v1/*` that code means a feature
            this deployment does not offer and must not be retried, and a
            client's retry rule is written once for every answer.
        reason:
          type: string
          description: Machine-readable name of the refusal.
          enum: [allowance_no_deposit, bad_key_format, call_not_found, compute_limit_too_low, expires_too_soon, insufficient_allowance, insufficient_balance, internal_error, invalid_key, invalid_secrets_ref, invalid_version_key, keystore_error, max_per_call_exceeded, missing_payment_key, no_bound_identity, no_deposit, operation_limit_reached, policy_row_not_owner, calls_suspended, out_of_funds, project_not_allowed, project_not_found, rate_limit_exceeded, upstream_unavailable, tee_session_required, timeout, call_already_in_flight, trial_exhausted, trial_expired, trial_key_not_purchasable, grant_key_not_purchasable, invalid_request, unknown_operation, vault_not_verified, vault_unlocked, wallet_not_yours, wk_is_not_a_payer]
        expires_at:
          type: string
          format: date-time
          description: On `trial_expired` only — when the trial ended.
        used:
          type: integer
          description: On `trial_exhausted` only — the calls the trial key has made.
        limit:
          type: integer
          description: On `trial_exhausted` — the calls a trial grants. On `operation_limit_reached` — the operation's ceiling, with `window` and `operation` beside it.
      required: [error, reason]
    CallTimedOut:
      type: object
      properties:
        error: { type: string }
        reason: { type: string, enum: [timeout] }
        call_id: { type: string, format: uuid }
        poll_url: { type: string }
    # ----- Payment keys and subscriptions -----
    CreatePaymentKeyRequest:
      type: object
      properties:
        initial_deposit_usdc:
          type: string
          description: Dollars, e.g. `"1.00"`. Mutually exclusive with `initial_deposit_near`.
        initial_deposit_near:
          type: string
          description: |
            NEAR, swapped to the stablecoin through Intents — mainnet only.
        project_ids:
          type: array
          items: { type: string }
          description: |
            The scope, fixed at creation. `owner/*` allows a whole namespace.
        max_per_call:
          type: string
          description: Dollars. `"0"` or absent means no limit.
    CreatePaymentKeyResponse:
      type: object
      properties:
        nonce: { type: integer }
        owner: { type: string }
        payment_key:
          type: string
          description: |
            Shown once. Store it: a call presents it as `X-Payment-Key`, and it
            cannot be re-issued.
        store_secrets_tx: { type: string }
        top_up_tx: { type: [string, 'null'] }
    SubscriptionStatus:
      type: object
      properties:
        owner: { type: string }
        nonce: { type: integer }
        has_subscription:
          type: boolean
          description: |
            A subscription on this key: an allowance with an end, bought or
            given by the operator. Never true for a trial key; a trial the
            operator converted to a subscription reports `true`, with its
            `expires_at`.
        wallet_account:
          type: string
          description: |
            The custody wallet this key belongs to, when it belongs to one.
            Absent for a key owned by a named account. Read from the key's
            `owner`.
        expires_at: { type: [string, 'null'] }
        expired: { type: boolean }
        trial:
          type: object
          description: |
            Present for a TRIAL key and for nothing else — and then the three
            `allowance_*` figures are absent. A trial is a number of calls; the
            allowance behind it is the operator's and is not a budget.
          properties:
            calls: { type: integer, description: How many calls a trial is. }
            calls_used: { type: integer }
            calls_left: { type: integer, description: Zero means the next call answers `trial_exhausted`. }
        allowance_total_usd: { type: [string, 'null'], description: Absent for a trial key. }
        allowance_spent_usd: { type: [string, 'null'], description: Absent for a trial key. }
        allowance_available_usd: { type: [string, 'null'], description: Absent for a trial key. }
        balance:
          type: string
          description: Money on the key. Nets out anything currently reserved by a call in flight.
        withdrawable: { type: string }
        connector_namespace: { type: string }
        connectors:
          type: array
          items:
            type: object
            properties:
              connector_id: { type: string }
              name: { type: string }
              endpoint: { type: string }
              project_id: { type: string }
              operations:
                type: array
                items:
                  type: object
                  properties:
                    operation: { type: string }
                    price_usd: { type: string }
        connectors_in_scope: { type: boolean }
    AgentSecretPubkey:
      type: object
      properties:
        pubkey:
          type: string
          description: X25519 public key, hex. Encrypt-only.
        seed:
          type: string
          description: |
            `project:{project_id}:{agent_account}` — returned so a mismatch is
            visible rather than silent.
        agent_account:
          type: string
          description: The secret's name AND its owner.
    PreparedAgentSecret:
      type: object
      properties:
        contract_id: { type: string }
        method_name: { type: string, enum: [store_agent_secret] }
        args:
          type: object
          description: Complete arguments, including the agent wallet's signature.
        deposit: { type: string, description: yoctoNEAR; the contract refunds the excess. }
        gas: { type: string }
        agent_account: { type: string }
    PreparedAgentSecretDelete:
      type: object
      properties:
        contract_id: { type: string }
        method_name: { type: string, enum: [delete_agent_secret] }
        args:
          type: object
          description: Complete arguments, including the agent wallet's signature.
        gas: { type: string }
        agent_account: { type: string }
    # ----- Primitives -----
    Chain:
      type: string
      enum: [near, ethereum, polygon, base, arbitrum, optimism, bsc, avalanche, hyperevm, hood, solana, bitcoin]
      description: >-
        Supported chain identifier. The EVM chains (ethereum, polygon, base,
        arbitrum, optimism, bsc, avalanche, hyperevm, hood) all share ONE derived
        address (a single secp256k1 key) and are signable via
        `/wallet/v1/evm/*`; `hyperevm` (Hyperliquid's EVM, chain id 999) is
        signable but not a deposit or withdraw chain. `hood` is Robinhood Chain,
        an Arbitrum L2 that bridges both ways through 1Click.
        `solana` has its own derived ed25519 address and is signable via
        `/wallet/v1/solana/*`. `bitcoin` can be derived in the keystore but is
        not yet serviced by wallet v1. An endpoint that serves fewer chains
        than this list (balance, transfer and delete are NEAR-only; withdraw
        takes `WithdrawChain`) answers 400 for the ones it does not.

    SubPath:
      type: string
      pattern: '^[a-z0-9][a-z0-9._-]{0,63}$'
      description: >-
        A sub-key of the wallet's EVM key: a distinct secp256k1 key, and so a
        distinct `0x` address, of the same wallet
        (`subkey:{id}:evm:{sub_path}` in the keystore). Omitted or empty means
        the wallet's own key. EVM chains only; a Solana or NEAR endpoint refuses
        it. A sub-key is a separate address under the wallet's one authority,
        not a separate authority: any holder of the wallet's API key can sign
        for any path, and the same `evm_sign` capability governs every path.
        Nothing about a sub-key is stored; its address is derived on request,
        like the wallet's own.

    NearOnlyChain:
      type: string
      enum: [near]
      default: near
      description: >-
        `near` is the only value these endpoints take. Narrower than `Chain` on
        purpose: a transfer or an account delete is a NEAR operation, and naming
        another chain answers 400 rather than doing something elsewhere.

    WithdrawChain:
      type: string
      description: >-
        A chain funds can be withdrawn to: `near` directly, every other chain
        the 1Click token catalog lists (`GET /wallet/v1/tokens`, the
        `chains` of its entries) through the 1Click bridge — 37 chains on
        2026-10-14, read from the catalog every hour, so a chain 1Click adds
        is served with no release. Spelled as 1Click's id (`eth`, `sol`,
        `ton`, `xrp`) or, for the chains that have one, the long name
        (`ethereum`, `solana`, `zcash`); case does not matter. A chain the
        catalog does not list answers `400 unsupported_chain`, naming what it
        does list. Neither a subset nor a superset of `Chain` — `hyperevm` is
        signable but not bridged, and `hypercore` (Hyperliquid's L1, whose
        accounts are EVM addresses) is bridged but not signable: `to` is a
        HyperCore account, and 1Click credits the USDC to its perps balance.
        `to` is checked for shape on the chains the wallet derives addresses
        on (EVM, Solana, NEAR, Bitcoin); on any other chain 1Click judges the
        address at the quote, before anything moves, and a refusal comes back
        as `upstream_rejected` in its words.

    RequestType:
      type: string
      description: |
        Tracked async request / policy transaction type. `withdraw` is a
        same-chain intents withdrawal; `cross_chain_withdraw` is a separate type
        for 1Click bridge-out (a policy must list it explicitly — it is NOT
        folded into `withdraw`). `confidential` covers every confidential-shard
        op (shield / unshield / withdraw / transfer / swap). The deposit family
        (`intents/deposit`, `storage-deposit`, cross-chain deposit) all gate as
        `call`. `limit_order` is a rested 1Click order and, like
        `cross_chain_withdraw`, its own type: permitting swaps or cross-chain
        exits does not permit it. `intents_storage_deposit` pays a token
        registration from the intents wNEAR balance and is its own type:
        `call` does not permit it. `policy_update` is a write to a locked
        policy awaiting the approvers' quorum (`signPolicy`); it is never
        subject to `excluded_types` — the lock is its own check.
      enum:
        - call
        - transfer
        - withdraw
        - cross_chain_withdraw
        - limit_order
        - deposit
        - swap
        - confidential
        - intents_storage_deposit
        - policy_update

    RequestStatus:
      type: string
      description: >-
        `partially_failed` occurs only for `w_execute_extension` (Agent
        Connect's extension door) and is a NORMAL outcome, not an error: the
        wallet detaches its promises, they execute concurrently and
        independently, and one failing neither reverts the others nor undoes
        the value they moved. Read `result.promises[]` for which did what.
      enum:
        - pending_deposit
        - processing
        - success
        # What a payment check's request row says from the moment it is
        # written: the check exists. Every other operation ends in `success`.
        - completed
        - partially_failed
        - failed
        - refunded
        - pending_approval
        - approved
        - rejected
        - cancelled
        - needs_review

    ErrorCode:
      type: string
      enum:
        - missing_auth
        - invalid_api_key
        - session_required
        - session_replaced
        - not_wallet_owner
        - missing_wallet_id
        - invalid_wallet_id
        - missing_signature
        - invalid_signature
        - missing_timestamp
        - timestamp_expired
        - wallet_frozen
        - policy_denied
        - not_approver
        - insufficient_balance
        # 400, same-chain withdraw pre-conditions, each the name the dry-run
        # answers in `reason`: a NEP-141 recipient with no storage on the
        # token contract (`POST /wallet/v1/intents/storage-deposit` paid in
        # intents wNEAR, `POST /wallet/v1/storage-deposit` paid in NEAR, or another
        # `to`), and a native NEAR withdraw to a named account that does not
        # exist (`native_withdraw` would burn the wNEAR). Terminal for the
        # request as sent; nothing moved.
        - storage_not_registered
        - recipient_not_found
        # 402, and about the SIGNER rather than the request: the account that
        # would send the transaction cannot pay for it. `wallet_underfunded`
        # names the wallet's own NEAR account and what the call costs;
        # `vault_underfunded` is the same shortfall on a vault. Actionable and
        # permanent until somebody sends funds — not something to retry on a
        # timer.
        - wallet_underfunded
        - vault_underfunded
        - invalid_address
        - rate_limited
        # 400. The chain is not one the 1Click token catalog lists right now.
        # The set is the catalog's, read every hour: a chain 1Click adds is
        # served with no release, and the message names what the catalog does
        # list. Not retried.
        - unsupported_chain
        # 400. The asset is not one this route can carry: not in the catalog,
        # no listing of its symbol on the destination chain, 1Click's
        # "tokenIn is not valid", or a `1cs_v1:` id on another chain given as
        # a SOURCE (a source is named by its id on intents.near). Not retried.
        - unsupported_token
        # 400. 1Click found no route with liquidity for this pair at this
        # amount ("No liquidity available"). The request is well formed; the
        # market is not there. Try another amount or route, not the same again.
        - no_liquidity
        # 400. 1Click refused the request on grounds of its own — an amount
        # under the bridge minimum, a parameter it would not take — and
        # `message` is its text, verbatim. The same request fails the same way.
        - upstream_rejected
        # 429 + Retry-After. The wallet's counted ceiling on a custody operation
        # (1000 `custody:*` per day on the free tier, dry-runs included). The
        # body is OperationLimitReachedResponse: the ceiling, its window and
        # when it clears. The name `/call` answers its own ceiling with.
        - operation_limit_reached
        - request_not_found
        - approval_not_found
        - already_approved
        - bad_request
        - conflict
        - duplicate_idempotency_key
        - onchain_tx_failed
        - internal_error
        - keystore_error
        - service_unavailable
        # Same status as `service_unavailable`, opposite instruction: this one
        # clears by itself and carries a Retry-After. They were one code once,
        # and the header could then only be right for one of them.
        - chain_unavailable
        # 503 + Retry-After: this deployment's database could not serve the
        # request right now. The name `/call` answers the same condition with,
        # so one retry rule covers both doors. Any other database failure is
        # `internal_error` (500), which is not retried; neither carries the
        # database's own text.
        - upstream_unavailable
        # 503 + Retry-After. 1Click did not answer for the route: a 5xx, a
        # timeout, a connection failure, or an answer that says nothing about
        # it ("Failed to get quote", "Internal server error"). Nothing is known
        # about the route — a dry-run answers this as an error, never as a
        # route that fails. Retry after the header.
        - route_unavailable
        # 422, and the OPPOSITE instruction to `chain_unavailable` above. The
        # chain ANSWERED, and the answer was about the account asked rather than
        # a value: no such account, no contract code, no such method, or code
        # that panicked. No number of retries changes that, so no Retry-After is
        # sent. A balance route answers this rather than a figure: a contract
        # that cannot say what an account holds has not said it holds nothing.
        - chain_refused
        # The node's own validation refused to admit the transaction — expired,
        # bad nonce, unknown signer. Nothing executed and nothing was charged.
        - tx_rejected_by_node
        - confidential_jwt_expired
        # Agent Connect. The bodies for these two carry MORE than the uniform
        # {error, message} shape — see AgentConnectDeniedResponse and
        # WalletBusyResponse — and a client that only switches on the code
        # throws away the fields that tell it what to do next.
        - agent_connect_denied
        - wallet_busy
        - binding_not_found

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
        details:
          type: object
          additionalProperties: {}

    OnChainTxFailedError:
      type: object
      required: [error, tx_hash]
      description: |
        Body of the 422 `onchain_tx_failed` response. Unlike `ErrorResponse`,
        it carries the real `tx_hash` (the transaction IS on chain) and the raw
        NEAR execution-failure JSON.
      properties:
        error:
          type: string
          const: onchain_tx_failed
        message:
          type: string
          description: Decoded FunctionCallError / contract panic string.
        tx_hash:
          type: string
          description: Hash of the broadcast transaction. Real — the tx is on chain.
        failure:
          description: Raw NEAR execution-failure JSON (e.g. `ActionError`).

    # ----- Registration -----
    RegisterRequest:
      type: object
      description: |
        For the common case (anonymous wallet on OutLayer's shared master),
        send empty `{}`. Optional fields enable advanced flows:

        - `vault_id`: bind this wallet to an existing customer-owned vault,
          so the wallet's master is derived through the vault's per-customer
          MPC-derived master instead of OutLayer's shared default. The vault
          must already be deployed and verified — **vault deployment is not
          done through this endpoint**. Use the dashboard
          (https://outlayer.ai/vault) or the CLI
          (`outlayer vault init`) to deploy. Reference:
          https://outlayer.ai/docs/vaults
        - `account_id` + `pubkey` + `message` + `signature`: bind the wallet
          to a verified NEAR account via NEP-413 proof-of-ownership. Used
          by clients that want operational keys (`wk_...`) tied to a real
          NEAR account.
      properties:
        account_id:
          type: string
          description: NEAR account ID to bind the wallet to (requires NEP-413 signature).
        seed:
          type: string
          description: Reserved for deterministic-wallet derivation. Most callers leave unset.
        pubkey:
          type: string
          description: NEP-413 signer pubkey (paired with `account_id` + `signature`).
        message:
          type: string
          description: NEP-413 message that was signed.
        signature:
          type: string
          description: NEP-413 signature over `message`.
        vault_id:
          type: string
          description: |
            ID of a deployed and verified customer vault (e.g. `vault.alice.near`).
            Binding is permanent — the resulting API key is tied to this vault
            for its lifetime. All subsequent operations on the API key
            automatically derive keys through the per-vault master; you do
            NOT pass `vault_id` on every call.

    RegisterResponse:
      type: object
      required: [wallet_id, near_account_id]
      properties:
        wallet_id:
          type: string
          format: uuid
        api_key:
          type: string
          description: Shown once. Not retrievable later — save it now.
        near_account_id:
          type: string
        handoff_url:
          type: string
          format: uri
          description: Dashboard URL where the controller sets policy.
        trial:
          $ref: '#/components/schemas/TrialInfo'

    TrialInfo:
      type: object
      description: |
        The trial OFFER. Registering grants nothing; the wallet claims its key
        with `POST /trial-key` when it wants one.
      properties:
        available:
          type: boolean
          description: Whether this deployment offers a trial at all — not whether this wallet may still claim one.
        calls:
          type: integer
          description: How many connector calls a trial is. There is no other budget.
        days:
          type: integer
          description: A trial is the wallet's first `days` days, counted from the wallet's creation — it can be claimed until then and stops working then, whenever it was claimed.
        claim_url: { type: string }
        scope:
          type: string
          description: What a trial key may call.

    # ----- Wallet read -----
    AddressResponse:
      type: object
      required: [wallet_id, chain, address, public_key]
      properties:
        wallet_id:
          type: string
        chain:
          $ref: '#/components/schemas/Chain'
        sub_path:
          $ref: '#/components/schemas/SubPath'
        address:
          type: string
        public_key:
          type: string
        vault_id:
          type: [string, 'null']
        asset_account_id:
          type: [string, 'null']
          description: >-
            Agent Connect: the bound named asset account. Always present for
            chain=near and `null` when the wallet has no binding — a key that
            is simply absent is a different answer to a client that checks for
            one.
        executor_account_id:
          type: [string, 'null']
          description: >-
            Agent Connect: the executor identity. For chain=near always equal
            to `address`.
        gas_balance:
          type: [string, 'null']
          description: >-
            Agent Connect: the executor's native balance in yoctoNEAR, cached
            about 30 seconds. Present only for chain=near on a BOUND wallet —
            it is here so whoever funds the executor learns the account and
            whether it needs funding in one call. Absent also when the chain
            could not be read, which is not a balance of zero.

    BalanceResponse:
      type: object
      required: [balance, token, account_id, account]
      properties:
        balance:
          type: string
          description: Amount in token's smallest unit.
        token:
          type: string
        account_id:
          type: string
        account:
          type: string
          enum: [asset, executor]
          description: >-
            Which identity `account_id` is, so the figure cannot be
            misattributed. `executor` for every wallet without a binding.

    OperationLimitReachedResponse:
      type: object
      required: [error, message, limit, window, operation, terminal]
      description: >-
        A `429` meaning the wallet's counted ceiling on this custody operation
        is reached. `message` reads "limit reached: 1000 per day for custody:*";
        the fields carry the same facts for a program. `terminal` is false:
        this clears by waiting (`retry_after_seconds`, also sent as
        `Retry-After`, null when the counter's remaining life could not be
        read) or by a subscription on the wallet's own key.
      properties:
        error:
          type: string
          enum: [operation_limit_reached]
        message:
          type: string
        limit:
          type: integer
          description: The ceiling that was reached.
        window:
          type: string
          description: The period the ceiling is counted over, e.g. `day`.
        operation:
          type: string
          description: The operation the ceiling is on, e.g. `custody:*`.
        terminal:
          type: boolean
          enum: [false]
        retry_after_seconds:
          type: [integer, 'null']
          description: Seconds until the counter that refused this clears; null when unknown.

    WalletBusyResponse:
      type: object
      description: >-
        A `409` meaning another money-moving operation is using this wallet.


        A wallet runs one spend at a time. The check "does this fit the limit?"
        and the write that satisfies it are seconds apart, so two overlapping
        operations would both read a total that neither had written yet and
        both pass — spending a daily cap twice. Serializing per wallet is what
        makes the counters true, and it cannot be done in SQL instead: the
        limits live in the customer's encrypted policy, which only the enclave
        can read.


        Callers wait a short grace first, so two quick calls in a row simply
        queue and never see this. It appears when the operation in front is a
        long one — a swap or a cross-chain withdraw. Poll
        `in_flight_request_id` when it is set, rather than retrying blindly;
        when it is `null`, `in_flight_operation` still says what to wait for.
      required: [error, message]
      properties:
        error:
          type: string
          enum: [wallet_busy]
        message:
          type: string
        in_flight_request_id:
          type: [string, 'null']
          format: uuid
          description: >-
            The request holding the wallet, and only ever one that
            `GET /wallet/v1/requests/{request_id}` can already answer. `null`
            never means the wallet is free: it means there is nothing to poll,
            and `message` says which of the two reasons applies — the holder
            has not written its request row yet (retrying shortly yields an
            id), or the operation writes no request row at all, as a
            cross-chain deposit intent does. An id is deliberately withheld
            until its row exists, because one handed out earlier answers `404`
            and reads as a request that was lost.
        in_flight_operation:
          type: [string, 'null']
          description: >-
            What the holder is doing. Present even when
            `in_flight_request_id` is `null`, and worth branching on: a
            transfer clears in seconds while a cross-chain withdraw can run for
            many minutes, and that is the difference between retrying at once
            and backing off. `repair` is the odd one — a read of a request left
            unresolved settles it under the same lock, and that finishes
            quickly.
          enum:
            # `null` belongs in the list because the field is nullable: the
            # coordinator answers `busy` without an operation in the sliver
            # between a holder taking the wallet and announcing itself. An enum
            # that omits it would declare that moment impossible.
            - null
            - transfer
            - call
            - swap
            - delete
            - withdraw
            - cross_chain_withdraw
            - cross_chain_deposit
            - limit_order
            - storage_deposit
            - intents_transfer
            - intents_deposit
            - intents_storage_deposit
            - confidential
            - confidential_deposit
            - repair
            - policy_update

    AgentConnectDeniedResponse:
      type: object
      description: >-
        A `403` from the Agent Connect pre-flight: the request was refused
        BEFORE it was signed, so no gas was spent, and the refusal names the
        rule the wallet contract would have panicked on.


        Structured rather than prose because a client has to route on it. Read
        `terminal` first: `true` means retrying is pointless and the OWNER must
        act — issue a new grant, re-provision the executor, fund the account,
        or rewrite the request. `false` means the same request may succeed
        later with nothing changed (a freeze lifted, a parked account
        reactivated, recognized wallet code restored, the account's registry
        caught up with it).
      required: [error, message, class, terminal]
      properties:
        error:
          type: string
          enum: [agent_connect_denied]
        message:
          type: string
          description: One sentence the owner can act on.
        class:
          type: string
          description: >-
            Stable machine class. Binding liveness:
            `executor_not_in_control_set`, `lease_expired`, `account_expired`,
            `account_frozen`, `account_not_active`,
            `unsupported_wallet_implementation`, `unrecognized_wallet_code`,
            `registry_disagrees` (a leased account whose collection's
            `nft_token` does not confirm the account's own `nft_item_info` —
            reversible, the registry may trail by a block),
            `binding_evidence_mismatch`, `chain_status_unreadable`. Spend
            grant: `grant_missing`, `grant_expired`, `grant_unreadable`,
            `grant_exhausted`, `receiver_not_granted`, `token_not_granted`,
            `token_budget_exceeded`, `collection_not_granted`,
            `item_not_granted`,
            `own_collection_refused`, `insufficient_vs_reserve`, and
            `grant_shape_violation:<subcode>` where subcode is one of
            `refund_target_not_allowed`, `grant_call_must_stand_alone`,
            `grant_call_deposit`, `grant_approval_not_allowed`,
            `grant_args_unreadable`, `grant_method_not_allowed`,
            `grant_action_not_allowed`.
        terminal:
          type: boolean
          description: >-
            `true` — do not retry. Every grant-layer class is terminal: the
            chain's answer does not change while the request and the grant
            stay as they are.
        promise_index:
          type: [integer, 'null']
          description: >-
            Which promise inside the decoded request the rule is about; `null`
            for a refusal about the request or the binding as a whole.
        additional_violations:
          type: integer
          description: >-
            How many further violations the same request carries beyond the one
            reported — whether fixing this one ends the matter.

    PutBindingRequest:
      type: object
      required: [asset_account_id]
      properties:
        asset_account_id:
          type: string
          description: >-
            Named NEAR account this wallet operates: the leased asset account
            (`agent.tla`) for `hos_lease`, the owner's own account
            (`user.near`) for `personal_account`.
        kind:
          type: string
          enum: [hos_lease, personal_account]
          default: hos_lease
          description: >-
            Binding mode. Omitted means `hos_lease`, byte-for-byte the
            pre-kind behavior.
        owner_account_id:
          type: string
          description: >-
            `hos_lease`: required; the account that authorized the lane, as
            reported at provisioning (informational — authorization is proven
            by the on-chain control set). `personal_account`: optional, and
            must equal `asset_account_id` — the owner IS the account.
        impl_version:
          type: integer
          description: >-
            `hos_lease` only (REQUIRED there, REJECTED for
            `personal_account`): wallet implementation version, read from the
            asset account's `hos_lease()`. Pins which request decoder applies;
            an unsupported value is rejected at binding time (terminal, do
            not retry).
      example:
        asset_account_id: agent.tla
        owner_account_id: owner.near
        impl_version: 6

    BindingResponse:
      type: object
      required:
        [binding_id, wallet_id, kind, asset_account_id,
         executor_account_id, binding_status, created_at]
      properties:
        binding_id:
          type: string
        wallet_id:
          type: string
        kind:
          type: string
          enum: [hos_lease, personal_account]
        asset_account_id:
          type: string
        executor_account_id:
          type: string
          description: >-
            The OutLayer execution identity — register it in the account's
            extension set (and, for hos_lease, provision its spend grant).
            NOTE: the response deliberately carries no owner. `owner_account_id`
            is accepted at PUT as the provisioning receipt House of Stake hands
            the integrator, and is stored — but it is checked for shape only and
            compared against nothing, so returning it would present a claim as
            an established fact. Who holds a leased account is
            `nft_item_info.owner_id` on chain, and what ends a lane when it
            changes hands is the rotation pin — the item's `owner_id`,
            `rotation_epoch` and `rotation_seq` as read at activation: a
            different owner, or a different seq inside the same epoch, ends
            the binding; a new epoch under the same owner re-establishes it.
        binding_status:
          type: string
          enum: [pending, active, suspended, revoked]
          description: >-
            OutLayer's view only, not an attestation of chain state.
            `pending` until the executor is first observed live in the
            extension set; `suspended` on reversible faults (freeze,
            non-Active state, unsupported impl_version, unrecognized code
            hash); `revoked` is terminal (extension removed, lease/state
            expired, ownership rotated, or DELETE). Anything but `active`
            carries `status_reason`.
        status_reason:
          type: [string, 'null']
          description: >-
            Why the binding is not `active`: the fault class the last
            observation reported, in the vocabulary a refused spend uses
            (`AgentConnectDeniedResponse.class` — `executor_not_in_control_set`,
            `account_frozen`, `unsupported_wallet_implementation`,
            `unrecognized_wallet_code`, `registry_disagrees`, ...). Absent
            while `active` and until the first observation; on `revoked`, what
            ended the lane. A `pending` personal binding reads
            `executor_not_in_control_set` until the owner adds the executor.
        impl_version:
          type: [integer, 'null']
          description: Absent for kind=personal_account.
        decoder_version:
          type: [integer, 'null']
          description: >-
            Derived by OutLayer, never client-supplied. Absent for
            kind=personal_account, whose versioning is the account's code
            hash checked at verify time.
        created_at:
          type: string
          format: date-time
        gas_balance:
          type: [string, 'null']
          description: >-
            Executor's native NEAR balance in yoctoNEAR (GET only). Null when
            the RPC could not answer.
        gas_balance_low:
          type: [boolean, 'null']
          description: >-
            The executor is under `gas_balance_threshold` and will soon be
            unable to pay for transactions — top it up. `null` means the
            balance could not be read, which is UNKNOWN rather than low. Poll
            this endpoint; there is no separate low-gas notification.
        gas_balance_threshold:
          type: [string, 'null']
          description: yoctoNEAR floor `gas_balance_low` is measured against.
      example:
        binding_id: bnd_7f3a2b1c9d8e4f60a1b2c3d4e5f60718
        wallet_id: 9c3c9e10-1c1f-4f5e-9c4a-1d7b9a8f3c20
        kind: hos_lease
        asset_account_id: agent.tla
        executor_account_id: 9c3c9e101c1f4f5e9c4a1d7b9a8f3c20
        binding_status: pending
        impl_version: 6
        decoder_version: 1
        created_at: '2026-08-18T14:00:00Z'

    BindingSetupResponse:
      type: object
      required: [kind, asset_account_id, executor_account_id, code_hash, transactions]
      properties:
        kind:
          type: string
          enum: [personal_account]
        asset_account_id:
          type: string
        executor_account_id:
          type: string
        code_hash:
          type: string
          description: >-
            Base58 code hash of the published no-sign wallet global contract —
            the same artifact the verifier's allowlist pins.
        transactions:
          type: array
          description: >-
            One transaction, three actions; receiver = signer = the owner's
            account.
          items:
            type: object
            required: [signer_id, receiver_id, actions]
            properties:
              signer_id:
                type: string
              receiver_id:
                type: string
              actions:
                type: array
                items:
                  type: object
      example:
        kind: personal_account
        asset_account_id: user.near
        executor_account_id: 9c3c9e101c1f4f5e9c4a1d7b9a8f3c20
        code_hash: BwjDnyemmBhrCyuviDGpoQAm9mdjTfrX7ZjqgZB4MHvM
        transactions:
          - signer_id: user.near
            receiver_id: user.near
            actions:
              - type: UseGlobalContract
                code_hash: BwjDnyemmBhrCyuviDGpoQAm9mdjTfrX7ZjqgZB4MHvM
              - type: FunctionCall
                method_name: w_init
                args: {}
                gas: '30000000000000'
                deposit: '1'
              - type: FunctionCall
                method_name: w_execute_extension
                args:
                  request:
                    internal:
                      - op: add_extension
                        payload:
                          account_id: 9c3c9e101c1f4f5e9c4a1d7b9a8f3c20
                gas: '30000000000000'
                deposit: '1'

    DeleteBindingResponse:
      type: object
      required: [binding_status, cancelled_approvals]
      properties:
        binding_status:
          type: string
          enum: [revoked]
        binding_id:
          type: [string, 'null']
          description: The record that was ended; absent when there was nothing to end.
        cancelled_approvals:
          type: integer
          description: >-
            Pending multisig approvals targeting the asset account that were
            cancelled rather than left completable. The requests those
            approvals were gating are moved to `cancelled` in the same step —
            an approval cancelled on its own stops the execution but leaves the
            request at `pending_approval` for good, unable to complete and
            never saying so. Requests already past the decision (`processing`)
            are left alone: they may have bytes on the wire.

    TokenInfo:
      type: object
      required: [id, symbol, chains, decimals]
      properties:
        id:
          type: string
        symbol:
          type: string
        chains:
          type: array
          items:
            $ref: '#/components/schemas/Chain'
        decimals:
          type: integer
        defuse_asset_id:
          type: string

    TokensResponse:
      type: object
      required: [tokens]
      properties:
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/TokenInfo'

    # ----- Wallet write -----
    CallRequest:
      type: object
      required: [receiver_id, method_name]
      properties:
        receiver_id:
          type: string
        method_name:
          type: string
        args:
          type: object
          additionalProperties: {}
          description: Method arguments as a JSON object. Mutually exclusive with `args_base64`.
        args_base64:
          type: string
          description: Pre-encoded base64 args. Use for non-JSON encodings.
        gas:
          type: string
          description: Gas budget in TGas as a string. Defaults to `30000000000000` (30 TGas) server-side.
        deposit:
          type: string
          description: Attached NEAR deposit in yoctoNEAR. Defaults to `0` server-side.

    CallResponse:
      type: object
      required: [request_id, status]
      properties:
        request_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/RequestStatus'
        tx_hash:
          type: [string, 'null']
        result:
          type: [object, 'null']
          additionalProperties: {}
          description: >-
            For `w_execute_extension` this also carries `promises`: one entry
            per promise of the decoded request, in the order the request listed
            them, each with `index`, `receiver`, `status`
            (`success` | `failed` | `unknown`), `receipt_id` and the chain's own
            `failure` object where it failed. `unknown` means the promise's
            receipt was not found in the outcome — it is NOT read as success,
            and its amounts are not charged to the velocity counters. A call
            the wallet contract REFUSED carries `promises: []`: the refusal
            happened before anything was detached, so no promise exists to
            report on, and none of the request is charged to the counters —
            read `failure` for the contract's reason.
        approval_id:
          type: [string, 'null']
          format: uuid
        required:
          type: [integer, 'null']
        approved:
          type: [integer, 'null']
        request_hash:
          type: [string, 'null']
          description: >-
            Present on `pending_approval` — sha256(canonical_json(op)); sign to
            approve.

    TransferRequest:
      type: object
      description: |-
        Native transfer on a single chain. Canonical recipient field is
        `to` — matches `WithdrawRequest.to` and the dashboard. The legacy
        field name `receiver_id` is still accepted as an alias for
        backward compatibility with clients that predate the rename;
        sending BOTH in the same body is rejected as a deserialization
        error.
      required: [to, amount]
      properties:
        chain:
          allOf:
            - $ref: '#/components/schemas/NearOnlyChain'
          description: Chain to transfer on. Defaults to `near` server-side.
        to:
          type: string
          description: |-
            Recipient account id on `chain`. For NEAR, accepts both named
            accounts (`alice.near`) and 64-char implicit hex accounts.
          example: alice.near
        receiver_id:
          type: string
          deprecated: true
          description: |-
            **Deprecated alias for `to`.** Existing clients sending
            `receiver_id` continue to work; new clients should use `to`.
            Sending both `to` and `receiver_id` in the same body is
            rejected with a 400.
        amount:
          type: string
          description: Amount in the chain's smallest unit (yoctoNEAR, wei, …).

    DeleteRequest:
      type: object
      description: |-
        Irreversibly delete the wallet account and sweep its full NEAR balance
        to `beneficiary` (NEAR's native `DeleteAccount`).
      required: [beneficiary]
      properties:
        beneficiary:
          type: string
          description: |-
            Account that receives the deleted wallet's entire remaining
            balance. Must not be the wallet's own account.
          example: treasury.near
        chain:
          allOf:
            - $ref: '#/components/schemas/NearOnlyChain'
          description: Chain the account lives on. Defaults to `near` server-side.

    DeleteResponse:
      type: object
      required: [request_id, status, beneficiary]
      properties:
        request_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/RequestStatus'
        tx_hash:
          type: [string, 'null']
        beneficiary:
          type: string
        approval_id:
          type: [string, 'null']
          format: uuid
        required:
          type: [integer, 'null']
        approved:
          type: [integer, 'null']
        request_hash:
          type: [string, 'null']
          description: >-
            Present on `pending_approval` — sha256(canonical_json(op)); sign to
            approve.

    StorageDepositRequest:
      type: object
      required: [token]
      properties:
        token:
          type: string
          description: NEP-141 token contract (e.g. `wrap.near`). A `nep141:` prefix is stripped if present.
        account_id:
          type: [string, 'null']
          description: Account to register. Defaults to the wallet's own NEAR address.

    IntentsStorageDepositRequest:
      type: object
      additionalProperties: false
      required: [token]
      properties:
        token:
          type: string
          description: NEP-141 token contract, bare (`usdc.near`) or as its intents id (`nep141:usdc.near`).
        account_id:
          type: [string, 'null']
          description: Account to register. Defaults to the wallet's own NEAR account.

    IntentsStorageDepositResponse:
      type: object
      required: [request_id, status, token, account_id, already_registered]
      properties:
        request_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/RequestStatus'
        token:
          type: string
          description: The token contract, bare.
        account_id:
          type: string
        amount:
          type: [string, 'null']
          description: >-
            wNEAR paid, in yoctoNEAR: the contract's storage minimum. Absent
            when nothing was paid (`already_registered`).
        already_registered:
          type: boolean
          description: True when the account already had storage; nothing was signed or paid.
        intent_hash:
          type: [string, 'null']
        approval_id:
          type: [string, 'null']
          format: uuid
          description: Present only on `pending_approval` — the approval to vote on.
        required:
          type: [integer, 'null']
          description: Present only on `pending_approval` — approvals needed.
        approved:
          type: [integer, 'null']
          description: Present only on `pending_approval` — approvals collected so far.
        request_hash:
          type: [string, 'null']
          description: >-
            Present on `pending_approval` — sha256(canonical_json(op)); sign to
            approve.
        poll_url:
          type: [string, 'null']
          description: >-
            Present on `processing`: the intent was handed over and the
            registration is not visible yet. `GET` it for the outcome.

    StorageDepositResponse:
      type: object
      description: |
        Response for `storageDeposit`. `storage_deposit` is multisig-capable: on
        a multisig wallet that requires approval the response carries
        `status=pending_approval` with the `approval_id` / `required` / `approved`
        / `request_hash` fields populated (same shape as `CallResponse`); the
        deposit executes only after the approval threshold is met. On the direct
        path those fields are omitted and the single-sig response is byte-identical
        to before.
      required: [request_id, status, token, account_id, already_registered]
      properties:
        request_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/RequestStatus'
        tx_hash:
          type: [string, 'null']
        token:
          type: string
        account_id:
          type: string
        already_registered:
          type: boolean
          description: True when the account was already storage-registered; no transaction was sent.
        approval_id:
          type: [string, 'null']
          format: uuid
          description: Present only on `pending_approval` (multisig) — the approval to vote on.
        required:
          type: [integer, 'null']
          description: Present only on `pending_approval` — approvals needed.
        approved:
          type: [integer, 'null']
          description: Present only on `pending_approval` — approvals collected so far.
        request_hash:
          type: [string, 'null']
          description: >-
            Present on `pending_approval` — sha256(canonical_json(op)); sign to
            approve.

    IntentsDepositRequest:
      type: object
      required: [token, amount]
      properties:
        token:
          type: string
        amount:
          type: string

    IntentsDepositResponse:
      type: object
      required: [request_id, status]
      properties:
        request_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/RequestStatus'
        tx_hash:
          type: [string, 'null']

    WithdrawRequest:
      type: object
      required: [chain, amount]
      properties:
        chain:
          $ref: '#/components/schemas/WithdrawChain'
        to:
          type: string
          description: Destination address on the target chain.
        amount:
          type: string
        token:
          type: string
          description: >-
            Token ID, e.g. `nep141:usdt.tether-token.near`. For `chain=near`,
            omit (or use `near`/`native`) to deliver **native NEAR** (unwraps the
            wallet's wNEAR); use `nep141:wrap.near` to deliver wNEAR instead. For
            other chains, this is the source Intents asset bridged via 1Click.
            The asset's NEAR-side 1Click id `1cs_v1:near:nep141:<contract>` names
            the same balance and is accepted everywhere `nep141:<contract>` is; a
            `1cs_v1:` id on another chain is not a source (`unsupported_token`).
        async:
          type: boolean
          default: false
          description: >-
            When `true`, the call returns immediately with `status=processing`
            and a `poll_url`; the withdrawal settles in the background and the
            caller polls `GET /wallet/v1/requests/{request_id}` for the terminal
            status. **Recommended for cross-chain withdrawals**, whose bridge can
            take longer than the synchronous response window. When `false`
            (default) the call blocks until the withdrawal settles. Auth, policy
            and validation errors are returned synchronously in both modes; in
            async mode only an execution failure surfaces as the request's
            `failed` status.

    IntentsTransferRequest:
      type: object
      required: [to, amount, token]
      properties:
        to:
          type: string
          description: >-
            Recipient NEAR account id (named or 64-hex implicit). Credited inside
            `intents.near`; the account need not exist on-chain.
        amount:
          type: string
          description: Amount in minimal units (integer string).
        token:
          type: string
          description: >-
            Defuse asset id, e.g. `nep141:usdt.tether-token.near` (a bare
            `usdt.tether-token.near` is normalized to `nep141:`). To send NEAR,
            use `nep141:wrap.near`.

    WithdrawResponse:
      type: object
      description: |
        Response for `intentsWithdraw` (same-chain AND cross-chain). On a
        multisig wallet that requires approval, `status=pending_approval` and the
        `approval_id` / `required` / `approved` / `request_hash` fields are
        populated; approvers vote over `request_hash` (see `Nep413Auth`, or
        `ContractVoteAuth` for an approver without keys). On the
        direct path these fields are omitted/null.

        Also the response of `intentsTransfer`.

        A synchronous call answers once the withdrawal settles. When settlement
        outlasts its wait — the solver relay for a same-chain withdraw, the
        bridge for a cross-chain one — or anything fails after the funds were
        handed over, it answers `status=processing` with a `poll_url`, and the
        request settles on its own. It never answers an error once funds may
        have moved. The withdrawal runs to its outcome even if the caller
        disconnects.
      required: [request_id, status]
      properties:
        request_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/RequestStatus'
        approval_id:
          type: [string, 'null']
          format: uuid
        required:
          type: [integer, 'null']
        approved:
          type: [integer, 'null']
        request_hash:
          type: [string, 'null']
          description: >-
            Canonical request hash to sign when `status=pending_approval`
            (otherwise absent).
        poll_url:
          type: [string, 'null']
          description: >-
            Present when `status=processing` — after `async=true`, or a
            synchronous call whose settlement outlasted its wait. Poll this path
            (`GET /wallet/v1/requests/{request_id}`) for the terminal status.

    DryRunResponse:
      type: object
      properties:
        would_succeed:
          type: boolean
        reason:
          type: string
          description: >-
            Present when `would_succeed` is false, and the same name the real
            withdraw would answer in `error`. One of: `wallet_frozen`,
            `policy_denied`, `storage_not_registered` (wNEAR/NEP-141 recipient has no
            token storage), `recipient_not_found` (native NEAR to a non-existent named
            account — would burn the wNEAR), `insufficient_balance` (intents balance
            below the requested amount), `invalid_request` (body the real withdraw
            would reject with a 400), `no_liquidity` (1Click found no route with
            liquidity for this amount), `upstream_rejected` (1Click refused the
            cross-chain quote on grounds of its own — below the bridge minimum, for
            one; `message` is 1Click's text, e.g. "Amount is too low for bridge, try
            at least 303064"), `unsupported_token` (the destination chain lists no
            asset of that symbol, or 1Click does not know the asset). What was never
            assessed is not a reason: a 1Click or a catalog that did not answer is
            `503 route_unavailable` / `chain_unavailable`, a reached custody ceiling
            `429 operation_limit_reached`, an unknown chain `400 unsupported_chain`.
        message:
          type: string
        estimated_fee:
          type: string
        fee_token:
          type: string
        policy_check:
          $ref: '#/components/schemas/PolicyCheckResult'

    PolicyCheckResult:
      type: object
      description: |
        Policy evaluation summary attached to a dry-run. Present whenever the
        policy engine ran (i.e. not on a `wallet_frozen` short-circuit). On a
        `policy_denied` result `within_limits` is false and the optional fields
        are omitted; on an allowed / requires-approval result `within_limits` is
        true and `address_allowed` is populated.
      required: [within_limits]
      properties:
        within_limits:
          type: boolean
          description: True when the op is within the wallet's spending limits.
        daily_remaining:
          type: [string, 'null']
          description: Remaining daily allowance in minimal units, when the policy tracks one.
        address_allowed:
          type: [boolean, 'null']
          description: True when the destination address passed the policy allowlist.

    SwapRequest:
      type: object
      required: [token_in, token_out, amount_in]
      properties:
        token_in:
          type: string
          description: >-
            The asset sold, by its id on intents.near as `GET /wallet/v1/tokens`
            lists it: `nep141:…`, `nep245:…` (HOT-bridged), or its NEAR-side
            1Click id `1cs_v1:near:nep141:…`, which is the same asset. A
            `1cs_v1:` id on another chain names a delivery, not a balance, and
            is refused as `unsupported_token`.
        token_out:
          type: string
          description: >-
            The asset bought: `nep141:…`, `nep245:…`, or any `1cs_v1:` id the
            catalog lists, sent to 1Click as given. For a `1cs_v1:<chain>:…`
            destination 1Click decides which id lands on intents.near (ZEC
            bought as `1cs_v1:sol:spl:…` arrives as `nep141:zec.omft.near`);
            the response echoes `destination_asset` as sent.
        amount_in:
          type: string
        min_amount_out:
          type: string

    SwapResponse:
      type: object
      description: |
        Response for `intentsSwap`. Swap is a **Trusted** op, so on a multisig
        wallet it can return `status=pending_approval` with the
        `approval_id` / `required` / `approved` / `request_hash` fields populated
        (same shape as `WithdrawResponse`); the swap executes only after the
        approval threshold is met. On the direct path those fields are omitted and
        `amount_out` / `intent_hash` carry the settled result.

        When settlement outlasts the call's wait, or anything fails after the
        transfer was handed over, it answers `status=processing` with a
        `poll_url` (and the quoted `amount_out` when it has one), and the request
        settles on its own. The swap runs to its outcome even if the caller
        disconnects.
      required: [request_id, status]
      properties:
        request_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/RequestStatus'
        amount_out:
          type: string
        intent_hash:
          type: string
        approval_id:
          type: [string, 'null']
          format: uuid
        required:
          type: [integer, 'null']
        approved:
          type: [integer, 'null']
        request_hash:
          type: [string, 'null']
          description: >-
            Canonical request hash to sign when `status=pending_approval`
            (otherwise absent).
        poll_url:
          type: [string, 'null']
          description: >-
            Present when `status=processing` — poll this path
            (`GET /wallet/v1/requests/{request_id}`) for the terminal status.

    SwapQuoteResponse:
      type: object
      properties:
        amount_out:
          type: string
          description: |-
            Expected output in minimal units. Absent on a confidential
            swap-quote or withdraw dry-run when 1Click gave no estimate for the
            route; `hint` then says so. Such an answer is final for the route:
            asking again quotes the same way.
        min_amount_out:
          type: string
          description: Minimum guaranteed output (after slippage). Absent together with `amount_out`.
        deadline:
          type: string
          format: date-time
        time_estimate_seconds:
          type: integer
        hint:
          type: string
          description: Present only when `amount_out` is absent, and says why.

    DefuseAssetId:
      type: string
      description: |-
        NEAR Intents `defuse_asset_id`. Currently always a NEP-141 token
        identifier of the form `nep141:<contract>`. Format matches the
        [`TokenInfo.defuse_asset_id`](#/components/schemas/TokenInfo) field
        returned by `listTokens`.
      example: nep141:wrap.near

    DestinationAsset:
      allOf:
        - $ref: '#/components/schemas/DefuseAssetId'
      description: |-
        Defuse asset id the recipient will hold after the cross-chain deposit
        settles. Defaults to NEAR USDC.
      default: nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1

    ConfidentialDestinationAsset:
      allOf:
        - $ref: '#/components/schemas/DefuseAssetId'
      description: |-
        Defuse asset id that lands in the confidential balance. Omitted: USDC
        from any chain lands as NEAR USDC (the one USDC the confidential
        balance and every connector count in), and any other token lands as
        the SAME asset, bridged. There is no NEAR USDC default for a non-USDC
        token on this route — name `destination_asset` to swap on the way.

    DepositIntentSourceAsset:
      allOf:
        - $ref: '#/components/schemas/DefuseAssetId'
      description: |-
        NEAR Intents `defuse_asset_id` of the source token. The
        source chain is derived from this id.
      example: nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near

    DepositIntentChain:
      type: string
      description: |-
        Source chain. Supported: `near`, `ethereum`, `base`,
        `arbitrum`, `solana`, `bitcoin`, `bsc`, `polygon`,
        `optimism`, `avalanche`, `hood`, `hypercore`. `token` defaults
        to `USDC`, which not every chain carries — `hood` (Robinhood
        Chain) does not, so name a token it has. On `hypercore`
        (Hyperliquid's L1) `USDC` is the spot HIP-1 token, and `amount`
        is in its units: 8 decimals, not 6. `GET /wallet/v1/tokens` lists
        them, and naming one the chain lacks answers
        `unsupported_token` with what it does carry.
      example: ethereum

    DepositIntentToken:
      type: string
      description: Source token symbol on the origin chain. Defaults to `USDC`.
      default: USDC

    DepositIntentAmount:
      type: string
      description: Amount in the source token's smallest unit (e.g. `5000000` = 5 USDC).

    DepositRefundAddress:
      type: string
      description: |-
        Address on the source chain a failed cross-chain deposit refunds to,
        format-checked for the chain (`0x` + 40 hex on EVM chains and
        HyperCore, base58 on Solana, an account id on NEAR, `bc1` / `1` / `3`
        on Bitcoin). Used on a wallet without a policy, and on a wallet whose
        policy names no `refund_addresses` entry for a chain the wallet has
        no address of its own on (Bitcoin, Zcash, Tron, …) — there it is
        required. Otherwise the owner decides — the policy's
        `refund_addresses` entry for the chain, else the wallet's derived
        address on it — and this field is ignored; the response `hint` then
        says so and names the address a refund goes to.

    DepositIntentRequest:
      description: |-
        Request body for `intentsDepositCrossChain`. Two shapes accepted; see
        the `anyOf` branches below. `amount` is always required. The
        `destination_asset` field defaults to NEAR USDC
        (`nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1`)
        when omitted — see
        [`DestinationAsset`](#/components/schemas/DestinationAsset).

        Where a failed deposit refunds is resolved in this order: the wallet
        policy's `refund_addresses` entry for the source chain; a policy
        without one → the wallet's derived address on that chain when it has
        one — NEAR, Solana, EVM chains, HyperCore (the request's
        `refund_address` is ignored) — else the request's `refund_address`;
        no policy → the request's `refund_address`, else the derived address.
        No address at all is a `400`. See
        [`DepositRefundAddress`](#/components/schemas/DepositRefundAddress).

        Uses `anyOf` (not `oneOf`) deliberately — a request that supplies
        both `source_asset` and `chain` matches both branches; the
        coordinator resolves the conflict by preferring `source_asset` and
        logging a warning, so `oneOf`'s strict "exactly one match" rule
        would needlessly reject valid requests.
      anyOf:
        - title: BySourceAsset
          description: |-
            Preferred shape. The source chain is derived from the
            `source_asset` prefix (e.g. `nep141:eth-…` → ethereum,
            `nep141:base-…` → base, `nep141:btc.omft.near` → bitcoin,
            anything else `nep141:<contract>.near` → near).
          type: object
          required: [source_asset, amount]
          properties:
            source_asset:
              $ref: '#/components/schemas/DepositIntentSourceAsset'
            destination_asset:
              $ref: '#/components/schemas/DestinationAsset'
            amount:
              $ref: '#/components/schemas/DepositIntentAmount'
            refund_address:
              $ref: '#/components/schemas/DepositRefundAddress'
        - title: ByChainAndToken
          description: |-
            Legacy shape — kept for backwards compatibility. The coordinator
            resolves `(chain, token)` to a `source_asset` via the 1Click
            token catalog.
          type: object
          required: [chain, amount]
          properties:
            chain:
              $ref: '#/components/schemas/DepositIntentChain'
            token:
              $ref: '#/components/schemas/DepositIntentToken'
            destination_asset:
              $ref: '#/components/schemas/DestinationAsset'
            amount:
              $ref: '#/components/schemas/DepositIntentAmount'
            refund_address:
              $ref: '#/components/schemas/DepositRefundAddress'

    DepositIntentResponseFields:
      type: object
      description: The fields every cross-chain deposit response carries.
      required:
        - intent_id
        - deposit_address
        - amount
      properties:
        intent_id:
          type: string
        deposit_address:
          type: string
          description: |-
            One-time address on the source chain — send funds here. The
            address format depends on the resolved source chain:

            - `near` — 64-char hex (NEAR implicit account), e.g.
              `f51768dc0c4d4bbb78890262da9882dee2ee5b6c2fcf2c527e56c6eadcb54353`
            - `ethereum` / `base` / `arbitrum` / `bsc` / `polygon` /
              `optimism` / `avalanche` / `hood` — `0x` + 40 hex (EVM), e.g.
              `0x582290c0b2Cb60989B35FFF66049f3e3247355bc`
            - `hypercore` — `0x` + 40 hex as well, but a HyperCore account,
              not an EVM contract address: send with a HyperCore spot
              transfer (`spotSend`), never an EVM transaction
            - `solana` — base58, 32-44 chars (Solana), e.g.
              `5AmGa2Bcfajbytg55UUb4vCAAzKBMYKZNQwx5S2BH2qf`
            - `bitcoin` — `bc1…` (segwit) or `1…` / `3…` (legacy)

            Sending tokens to an address whose format doesn't match the
            source chain will lose the funds — always verify the format
            client-side before initiating the transfer.
        amount:
          type: string
        amount_out:
          type: string
          description: |-
            Amount credited after the cross-chain deposit fee, in the
            DESTINATION asset's smallest unit — not the origin's (HIP-1 USDC
            on `hypercore` has 8 decimals, NEAR USDC 6).
        min_amount_out:
          type: string
          description: Minimum credited after slippage, in the destination asset's smallest unit.
        expires_at:
          type: string
          format: date-time
          description: |-
            Deadline after which the deposit address is no longer
            guaranteed to be honored by 1Click. Absent if 1Click did not
            return a deadline.
        estimated_time_secs:
          type: integer
          description: |-
            Solver's estimate of deposit settlement time, in seconds. Absent
            if 1Click did not return an estimate.
        hint:
          type: string
          description: |-
            Non-binding advisory. Present when the resolved source chain is
            `near` — the caller's funds are already on NEAR and
            `POST /wallet/v1/intents/deposit` would do the deposit in one
            direct `ft_transfer_call` without the 1Click solver hop — and
            when the request's `refund_address` was ignored because the
            wallet policy governs refunds on that chain; then it names the
            address a failed deposit refunds to. Clients that don't read
            this field are unaffected.


    DepositIntentResponse:
      description: |-
        A public cross-chain deposit. `amount_out` and `min_amount_out` are
        always present: 1Click states them for every public route.
      allOf:
        - $ref: '#/components/schemas/DepositIntentResponseFields'
        - type: object
          required: [amount_out, min_amount_out]
          properties:
            amount_out:
              type: string
            min_amount_out:
              type: string

    DepositStatusResponse:
      type: object
      required: [intent_id, status, amount, deposit_address, created_at]
      properties:
        intent_id:
          type: string
        status:
          type: string
          enum: [pending, bridging, success, failed, expired]
        amount:
          type: string
          description: Deposit amount in the source token's minimal units.
        deposit_address:
          type: string
          description: The one-time source-chain address funds were to be sent to.
        created_at:
          type: string
          format: date-time
        expires_at:
          type: [string, 'null']
          format: date-time
          description: 1Click deadline after which the deposit address is no longer honored.
        result:
          type: [object, 'null']
          additionalProperties: {}

    # ----- Payment checks -----
    LimitOrderCreateRequest:
      type: object
      description: >-
        1Click's own order parameters, less the ones that are not the caller's
        to choose: the order is funded from one of this wallet's own balances
        (`deposit_type`) and refunded to that same balance.
      required: [base_asset, quote_asset, side, quantity, price]
      properties:
        base_asset:
          type: string
          description: Defuse asset id of the asset `quantity` is denominated in.
        quote_asset:
          type: string
          description: Defuse asset id of the asset `price` is denominated in.
        side:
          type: string
          enum: [sell, buy]
          description: >-
            `sell` — give `quantity` of base, receive quote at `price` or
            better. `buy` — receive `quantity` of base, pay quote at `price` or
            better.
        quantity:
          type: string
          pattern: '^[0-9]+$'
          maxLength: 65
          description: >-
            Base amount in the base asset's smallest units — digits only. A buy
            targets this output; a sell targets this input.
        price:
          type: string
          maxLength: 64
          pattern: '^([0-9]+\.?[0-9]*|\.[0-9]+)([eE][+-]?[0-9]+)?$'
          description: >-
            Quote per one WHOLE base, as 1Click reads it: a positive decimal,
            optionally with an exponent (`"5"`, `"0.25"`, `".5"`, `"1.2e1"`), no
            sign, spaces or separators, at most 64 characters. `"5"` is 5 quote
            per 1 base. These are 1Click's own bounds, not additional ones.
        recipient:
          type: string
          description: >-
            Where the filled output goes. Omitted → this wallet's own intents
            balance. Subject to the policy's address rules either way.
        recipient_type:
          type: string
          enum: [intents, confidential_intents, destination_chain]
          default: intents
          description: >-
            1Click's `recipientType`, lower-cased. `intents` — `recipient` is a
            NEAR account credited inside NEAR Intents. `confidential_intents` —
            the same, on the confidential shard, and the policy must then
            permit the `confidential` capability as well as `limit_order`.
            `destination_chain` — `recipient` is an address on the output
            asset's own chain, and is then required. Part of the terms
            approvers sign. With `deposit_type: confidential_intents` only
            `confidential_intents` (or omitting it) is accepted.
        deposit_type:
          type: string
          enum: [intents, confidential_intents]
          default: intents
          description: >-
            Which of this wallet's balances funds the order — and is refunded
            the unfilled remainder. `intents`: the public intents balance.
            `confidential_intents`: the confidential balance; the order then
            pays out to the confidential balance too (`recipient_type` must be
            `confidential_intents` or omitted — anything else is `400`, mixed
            routing is not offered), needs the `confidential` capability as
            well as `limit_order`, and is reachable only where confidential
            intents are configured (`503` otherwise).
        deadline:
          type: string
          format: date-time
          description: When the order expires. Omitted → 7 days.

    LimitOrder:
      type: object
      description: >-
        A 1Click order, as 1Click reports it — every attribute of its
        `LimitOrderAttributes`
        (https://1click.chaindefuser.com/docs/v0/openapi.yaml), with field
        names in snake_case and enumerated values in lower case, nothing
        renamed or left out. Enumerations are open — 1Click reserves values
        for order types that do not exist yet.
      required:
        - order_id
        - deposit_address
        - fill_status
        - payout_status
        - is_payout_status_final
        - base_asset
        - quote_asset
        - quantity
        - side
        - price
        - swap_view
        - recipient
        - recipient_type
        - refund_to
        - refund_type
      properties:
        order_id:
          type: string
        order_type:
          type: string
          description: '`limit`.'
        deposit_address:
          type: string
          description: Where the wallet's funding transfer went. Informational.
        deposit_mode:
          type: string
          description: Always `simple` — orders here are never created in memo mode.
        deposit_type:
          type: string
          description: >-
            Which of the wallet's balances funded the order: `intents` (the
            public intents balance) or `confidential_intents` (the
            confidential balance).
        fill_status:
          type: string
          description: >-
            Matching state: `awaiting_deposit`, `open`, `partially_filled`,
            `filled`, `pending_cancel`, `canceled`, `expired`, `untriggered`.
            NOT a terminal signal — see `is_payout_status_final`.
        payout_status:
          type: string
          description: Payout state, e.g. `not_started`, `completed`, `failed`.
        is_payout_status_final:
          type: boolean
          description: >-
            The ONLY terminal signal: filled output has been paid out and any
            unfilled amount refunded. `fill_status` reaching `canceled` or
            `filled` does not by itself mean the money has finished moving, and
            a `pending_cancel` order may still fill a last slice.
        payouts:
          type: object
          description: >-
            1Click's payout legs, verbatim: `withdrawal`, `allWithdrawals`,
            `refund`, each with a `status` and, once completed, a `txHash`.
        partial_fills:
          type: array
          description: >-
            Fills that have already executed, verbatim (`id`, `amountIn`,
            `amountOut`, `createdAt`, `updatedAt`). On a `partially_filled`
            order this is what says how much has filled so far.
          items:
            type: object
        deposited_amount:
          type: string
          description: How much of the input the order holds, smallest units.
        deposited_amount_formatted: { type: string }
        base_asset: { type: string }
        quote_asset: { type: string }
        quantity: { type: string }
        side:
          type: string
          enum: [sell, buy]
        price: { type: string }
        swap_view:
          type: object
          description: What the order moves, as 1Click computed it.
          properties:
            origin_asset: { type: string }
            destination_asset: { type: string }
            swap_type:
              type: string
              description: '`exact_input` on a sell, `exact_output` on a buy.'
            amount_in:
              type: string
              description: Sell — what the wallet sent.
            min_amount_out:
              type: string
              description: Sell — the least the order pays out.
            max_amount_in:
              type: string
              description: Buy — the most the wallet sent.
            amount_out:
              type: string
              description: Buy — exactly what the order pays out.
        app_fees:
          type: array
          description: >-
            Fees 1Click applied to the input of its own accord, verbatim.
            Reported because they come out of the wallet's funds.
          items:
            type: object
            properties:
              recipient: { type: string }
              fee:
                type: integer
                description: Basis points.
        recipient: { type: string }
        recipient_type:
          type: string
          description: '`intents`, `confidential_intents` or `destination_chain`.'
        refund_to:
          type: string
          description: Always this wallet's own account.
        refund_type:
          type: string
          description: >-
            Always the balance the order was funded from — the same value as
            `deposit_type`: the unfilled remainder comes back where the input
            came from.
        estimated_withdraw_fee: { type: string }
        estimated_withdraw_fee_formatted: { type: string }
        estimated_refund_fee: { type: string }
        estimated_refund_fee_formatted: { type: string }
        confidentiality:
          type: string
          description: Always `basic`.
        time_in_force:
          type: string
          description: '`gtc` — the only value 1Click offers.'
        deadline: { type: string }
        created_at: { type: string }
        transfer_intent_hash:
          type: string
          description: >-
            The intent that funded the order. The one field here that is this
            service's and not 1Click's.

    LimitOrderCreated:
      allOf:
        - $ref: '#/components/schemas/LimitOrder'
        - type: object
          required: [request_id]
          properties:
            request_id:
              type: string
              description: >-
                This create, as the rest of the API knows it (idempotency,
                audit). Follow the ORDER by `order_id`.

    LimitOrderPendingApproval:
      type: object
      required: [request_id, status, approval_id, required, approved, request_hash]
      properties:
        request_id: { type: string }
        status:
          type: string
          enum: [pending_approval]
        approval_id: { type: string }
        required: { type: integer }
        approved: { type: integer }
        request_hash:
          type: string
          description: What approvers sign over — the order's terms.

    LimitOrderProcessing:
      type: object
      required: [request_id, status, order_id, poll_url]
      description: >-
        The order exists and its funding was handed over, but was not
        confirmed in time (or the call failed after handing it over). Not an
        error, and not to be retried: the funding may land. The request
        settles on its own — from the chain for an order funded from the
        public intents balance, from the order itself (the deposit 1Click
        reports) for one funded from the confidential balance: `success` once
        the funding executed, or `failed` with `never_executed: true` once its
        deadline passed unused, and only then is the order cancelled.
      properties:
        request_id: { type: string }
        status:
          type: string
          enum: [processing]
        order_id:
          type: string
          description: The order being funded; follow it by `GET /wallet/v1/limit-orders/{order_id}`.
        poll_url:
          type: string
          description: '`GET /wallet/v1/requests/{request_id}` — the funding, until it settles.'

    LimitOrderCancelAllResponse:
      type: object
      required: [known, cancelled, failed, remaining, complete]
      properties:
        known:
          type: integer
          description: Unfinished orders this call asked 1Click to cancel (at most 50).
        cancelled:
          type: integer
          description: Cancels 1Click accepted.
        failed:
          type: integer
          description: Cancels that did not go through; those orders are still resting.
        remaining:
          type: integer
          description: Unfinished orders this call did not get to. Call again.
        complete:
          type: boolean
          description: >-
            True when nothing failed and nothing remains. False → orders may
            still be resting: call again.

    PaymentCheckCreateRequest:
      type: object
      required: [token, amount]
      properties:
        token:
          type: string
          description: >-
            Token to fund the check with. Accepts a `defuse_asset_id`
            (`nep141:<contract>`) or a bare NEP-141 contract id; normalized
            server-side.
        amount:
          type: string
          description: Amount in the token's minimal units. Must be > 0.
        memo:
          type: [string, 'null']
          description: Optional note (max 256 chars) surfaced to whoever peeks/claims the check.
        expires_in:
          type: [integer, 'null']
          format: int64
          minimum: 0
          description: >-
            Optional time-to-live in seconds from creation. After it elapses an
            unclaimed check reports `expired` and can no longer be claimed (only
            reclaimed by the creator).

    PaymentCheckCreateResponse:
      type: object
      required: [check_id, check_key, status, token, amount, created_at]
      properties:
        check_id:
          type: string
          format: uuid
          description: Server-side identifier for the check (used by status / reclaim).
        check_key:
          type: string
          description: >-
            The ephemeral account's ed25519 private key (64 hex chars). Bearer
            secret — whoever holds it can claim the funds. Returned ONCE, whatever
            `status` says.
        status:
          type: string
          enum: [unclaimed, creating, pending_approval]
          description: >-
            `unclaimed`: funded. `creating`: the funding transfer was handed to
            the relay and is not confirmed yet — follow `poll_url` until the
            check reads `unclaimed` (or `failed`: the transfer never executed and
            nothing moved). `pending_approval`: the wallet's policy requires the
            approvers' votes; the account holds nothing until the threshold is
            met — follow `poll_url` until the check reads `unclaimed` (or
            `failed`: vetoed, the approval expired unmet, or the check's own
            `expires_at` passed while it waited).
        poll_url:
          type: string
          description: Present with `status=creating` or `pending_approval` — the check's status endpoint.
        approval_id:
          type: string
          description: Present only on `pending_approval` — the approval to vote on.
        required:
          type: integer
          description: Present only on `pending_approval` — approvals needed.
        approved:
          type: integer
          description: Present only on `pending_approval` — approvals collected so far (0 at creation).
        request_hash:
          type: string
          description: >-
            Present only on `pending_approval` — sha256(canonical_json(op)) over
            the check's token and amount; what the approvers sign.
        token:
          type: string
        amount:
          type: string
        memo:
          type: [string, 'null']
        created_at:
          type: string
          format: date-time
        expires_at:
          type: [string, 'null']
          format: date-time

    PaymentCheckBatchCreateRequest:
      type: object
      required: [checks]
      properties:
        checks:
          type: array
          minItems: 1
          maxItems: 10
          items:
            $ref: '#/components/schemas/PaymentCheckCreateRequest'

    PaymentCheckBatchCreateResponse:
      type: object
      required: [checks]
      properties:
        checks:
          type: array
          items:
            $ref: '#/components/schemas/PaymentCheckCreateResponse'
        error:
          type: string
          description: >-
            Present when the batch stopped before its last check: why, and which
            checks were not created. Every check listed in `checks` was.

    PaymentCheckClaimRequest:
      type: object
      required: [check_key]
      properties:
        check_key:
          type: string
          description: The check's ephemeral private key (64 hex chars).
        amount:
          type: [string, 'null']
          description: >-
            Optional partial claim amount in minimal units. Omit to claim the
            full remaining balance.

    PaymentCheckClaimResponse:
      type: object
      required: [request_id, status, token, amount_claimed]
      properties:
        request_id:
          type: string
          format: uuid
          description: This claim as a request (`GET /wallet/v1/requests/{request_id}`).
        status:
          type: string
          enum: [claimed, partially_claimed, processing]
          description: >-
            The check's status after this claim, or `processing`: the transfer
            was handed over and is not confirmed yet — follow `poll_url`. The
            request ends `completed` (its `result` carries `amount_claimed`,
            `remaining`, `claimed_at`) or `failed` with `never_executed: true`
            (nothing moved; the check can be claimed again).
        token:
          type: string
        amount_claimed:
          type: string
        remaining:
          type: string
          description: >-
            Amount still claimable on the check after this claim (minimal units).
            Absent while `processing`.
        memo:
          type: [string, 'null']
        claimed_at:
          type: string
          format: date-time
          description: Absent while `processing`.
        intent_hash:
          type: [string, 'null']
          description: base58 solver-relay intent hash for the claim transfer, if returned.
        poll_url:
          type: string
          description: Present with `status=processing`.

    PaymentCheckReclaimRequest:
      type: object
      required: [check_id]
      properties:
        check_id:
          type: string
          format: uuid
          description: The `check_id` of a check the authenticated wallet created.
        amount:
          type: [string, 'null']
          description: >-
            Optional partial reclaim amount in minimal units. Omit to reclaim the
            full remaining balance.

    PaymentCheckReclaimResponse:
      type: object
      required: [request_id, status, token, amount_reclaimed]
      properties:
        request_id:
          type: string
          format: uuid
          description: This reclaim as a request (`GET /wallet/v1/requests/{request_id}`).
        status:
          type: string
          enum: [reclaimed, partially_reclaimed, processing]
          description: >-
            The check's status after this reclaim, or `processing` — follow
            `poll_url`, as for a claim.
        token:
          type: string
        amount_reclaimed:
          type: string
        remaining:
          type: string
          description: >-
            Amount still outstanding on the check after this reclaim (minimal
            units). Absent while `processing`.
        reclaimed_at:
          type: string
          format: date-time
          description: Absent while `processing`.
        intent_hash:
          type: [string, 'null']
          description: base58 solver-relay intent hash for the reclaim transfer, if returned.
        poll_url:
          type: string
          description: Present with `status=processing`.

    PaymentCheckStatusResponse:
      type: object
      required:
        - check_id
        - token
        - amount
        - claimed_amount
        - reclaimed_amount
        - status
        - created_at
      properties:
        check_id:
          type: string
          format: uuid
        token:
          type: string
        amount:
          type: string
          description: Original check amount in minimal units.
        claimed_amount:
          type: string
          description: Total claimed so far (minimal units).
        reclaimed_amount:
          type: string
          description: Total reclaimed so far (minimal units).
        status:
          type: string
          description: >-
            Lifecycle state: `pending_approval` (the wallet's approvers have not
            met the threshold yet; nothing is in the account), `creating`
            (funding transfer not confirmed yet), `unclaimed`, `claiming`,
            `partially_claimed`, `claimed`, `reclaiming`, `partially_reclaimed`,
            `reclaimed`, `failed` (the funding never executed, was vetoed, or
            its approval expired unmet; nothing moved), or the virtual `expired`
            (unclaimed and past `expires_at`). A read of a check with a transfer
            in flight settles it from the chain when the chain can already tell;
            a read of a check whose approval expired or was rejected marks it
            `failed`.
        memo:
          type: [string, 'null']
        created_at:
          type: string
          format: date-time
        expires_at:
          type: [string, 'null']
          format: date-time
        claimed_at:
          type: [string, 'null']
          format: date-time
        claimed_by:
          type: [string, 'null']
          description: Wallet id that claimed the check, if any.

    PaymentCheckListResponse:
      type: object
      required: [checks]
      properties:
        checks:
          type: array
          items:
            $ref: '#/components/schemas/PaymentCheckStatusResponse'

    PaymentCheckPeekRequest:
      type: object
      required: [check_key]
      properties:
        check_key:
          type: string
          description: The check's ephemeral private key (64 hex chars).

    PaymentCheckPeekResponse:
      type: object
      required: [token, balance, status]
      properties:
        token:
          type: string
        balance:
          type: string
          description: Live on-chain balance of the check's ephemeral account (minimal units).
        memo:
          type: [string, 'null']
        status:
          type: string
          description: Same status vocabulary as `PaymentCheckStatusResponse`.
        expires_at:
          type: [string, 'null']
          format: date-time

    SignMessageRequest:
      type: object
      required: [message, recipient]
      properties:
        message:
          type: string
        recipient:
          type: string
        nonce:
          type: string
          description: Base64-encoded 32-byte nonce. Auto-generated if omitted.
        format:
          type: string
          description: >-
            NEP-413 only. `raw` is **rejected** (`400 bad_request`) — use
            [`authSign`](#tag/Wallet/operation/authSign) for OutLayer NEAR-key
            auth. The field is retained only to return that redirect error.
          enum: [nep413]
          default: nep413

    SignMessageResponse:
      type: object
      properties:
        account_id:
          type: string
        signature:
          type: string
        signature_base64:
          type: string
        public_key:
          type: string
        nonce:
          type: string

    AuthSignRequest:
      type: object
      required: [purpose, seed]
      properties:
        purpose:
          type: string
          description: >-
            `bearer` → challenge `auth:<seed>:<ts>` (+`:<vault>` when `vault_id`
            set); `register` → `register:<seed>:<ts>`; `api-key` →
            `api-key:<seed>:<ts>`.
          enum: [bearer, register, api-key]
        seed:
          type: string
          description: Wallet seed — selects which sub-wallet's key signs.
        vault_id:
          type: string
          description: Vault scope — only valid for `purpose=bearer`.

    AuthSignResponse:
      type: object
      required: [auth_message, auth_timestamp, signature, public_key]
      properties:
        auth_message:
          type: string
          description: >-
            The exact challenge string the keystore built and signed — send this
            verbatim.
        auth_timestamp:
          type: integer
          format: int64
          description: Fresh server timestamp (unix seconds) baked into `auth_message`.
        signature:
          type: string
          description: Raw ed25519 signature over `auth_message`, base58 (no `ed25519:` prefix).
        public_key:
          type: string
          description: Signer public key in `ed25519:<base58>` form.

    # ----- Policy -----
    PolicyRules:
      type: object
      properties:
        transaction_types:
          type: array
          description: >-
            Allowed op types (allowlist). Omit to allow all. `cross_chain_withdraw`
            must be listed explicitly to permit bridging out (it is NOT covered by
            `withdraw`). The deposit family gates as `call`.
          items:
            $ref: '#/components/schemas/RequestType'
        allowed_tokens:
          type: array
          description: >-
            Token allowlist (defuse asset ids, or `"*"` for any). Omit or use
            `["*"]` to allow all tokens.
          items:
            type: string
        addresses:
          $ref: '#/components/schemas/AddressList'
        limits:
          $ref: '#/components/schemas/PolicyLimits'
        time_restrictions:
          $ref: '#/components/schemas/TimeRestrictions'
        rate_limit:
          $ref: '#/components/schemas/RateLimit'

    PolicyLimits:
      type: object
      description: |
        Per-period spending limits. The amount fields are maps of
        `token_id → amount` (use `"*"` as the key to match all tokens).
        `per_transaction` is STATELESS (enforced on every signature inside the
        TEE); `hourly` / `daily` / `monthly` and `hourly_tx_count` are STATEFUL
        velocity limits (checked against coordinator-supplied usage; best-effort
        under concurrency).
      properties:
        per_transaction:
          type: object
          additionalProperties:
            type: string
        hourly:
          type: object
          additionalProperties:
            type: string
        daily:
          type: object
          additionalProperties:
            type: string
        monthly:
          type: object
          additionalProperties:
            type: string
        hourly_tx_count:
          type: integer
          description: >-
            Max number of transactions per rolling hour (transaction-count rate
            limit; equivalent to `rate_limit.max_per_hour`).

    AddressList:
      type: object
      required: [mode, list]
      properties:
        mode:
          type: string
          enum: [whitelist, blacklist]
        list:
          type: array
          items:
            type: string

    TimeRestrictions:
      type: object
      properties:
        timezone:
          type: string
          description: IANA timezone name, e.g. `UTC` or `Europe/Berlin`.
        allowed_hours:
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 23
        allowed_days:
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 6
          description: 0 = Sunday, 6 = Saturday.

    RateLimit:
      type: object
      properties:
        max_per_hour:
          type: integer

    ApprovalConfig:
      type: object
      description: |
        Multisig approval configuration. When set, an op that trips the approval
        trigger returns `pending_approval` and executes only after `threshold`
        approvers sign. Applies to every op that moves funds, the Trusted kinds
        included (swap, confidential, cross_chain_withdraw, limit_order,
        payment_check); `excluded_types` names the types that skip it.
      properties:
        threshold:
          description: >-
            Number of approvals required — either a bare integer (e.g. `2`) or an
            object `{ "required": N }`.
          oneOf:
            - type: integer
              minimum: 1
            - type: object
              required: [required]
              properties:
                required:
                  type: integer
                  minimum: 1
        approvers:
          type: array
          items:
            $ref: '#/components/schemas/Approver'
        excluded_types:
          type: array
          description: Op types exempt from the generic approval trigger.
          items:
            $ref: '#/components/schemas/RequestType'
        locked:
          type: boolean
          description: |
            The policy is changed only with these approvers' quorum: every
            later `store_wallet_policy` — including the one that clears this
            flag — and every `delete_wallet_policy` waits for `threshold`
            votes (`signPolicy` answers `pending_approval`). The owner alone
            can set it, as a tightening, and cannot clear it. Freezing and
            unfreezing are not policy writes and stay the owner's. Accepted
            only with a reachable quorum: `threshold` ≥ 1 and at least that
            many approvers with an `id`.

    Approver:
      type: object
      required: [id]
      properties:
        id:
          type: string
          description: Approver's NEAR account id, e.g. `alice.near`.
        pubkey:
          type: string
          description: >-
            Optional. Pins the approver to this NEAR public key
            (`ed25519:<base58>`): only a NEP-413 vote signed by it counts, and a
            contract-wallet vote from this approver never does. Without it, a
            NEP-413 vote counts when signed by any full-access key of the account
            (checked on chain), and an approver without keys may vote through
            its wallet contract (`ContractVoteAuth`).
        role:
          type: string
          description: >-
            Optional. `admin` may also modify policy / freeze; `signer` may only
            approve transactions. Defaults to `signer` when omitted.
          enum: [admin, signer]

    Capability:
      type: object
      description: >-
        A single non-Built primitive toggle. All capabilities default to DENY
        except `sign_message`. `requires_approval` opts that primitive into
        multisig specifically.
      properties:
        allowed:
          type: boolean
        requires_approval:
          type: boolean

    RawSignCapability:
      type: object
      description: >-
        `raw_sign` — sign arbitrary raw bytes. `chains` is an optional allowlist;
        when absent, every chain **except `near`**. `near` is signed only when
        listed, with or without a policy: a raw signature by the NEAR key is any
        NEAR transaction, outside the structured policy — including a call to
        `intents.near` that hands the wallet's intents account to another key.
      properties:
        allowed:
          type: boolean
        requires_approval:
          type: boolean
        chains:
          type: array
          items:
            type: string

    SignMessageCapability:
      type: object
      description: >-
        `sign_message` — generic non-fund NEP-413 (e.g. dApp login). Defaults
        ALLOWED. `allowed_recipients` is a default-DENY allowlist of verifier
        recipients (NOT a blocklist); `intents.near` / `intents.far` are always
        excluded. This is NOT OutLayer auth (that is `authSign`).
      properties:
        allowed:
          type: boolean
        requires_approval:
          type: boolean
        allowed_recipients:
          type: array
          items:
            type: string

    EvmSignCapability:
      type: object
      description: >-
        `evm_sign` — EVM signing (EIP-712 typed-data / EIP-191 personal_sign /
        raw tx). **Default-DENY under a policy** (like the other fund-moving
        capabilities) — set `allowed: true` to permit. A wallet with no policy is
        unrestricted. CAVEAT (why it must be opt-in): an EIP-712 signature is
        itself fund-moving (EIP-3009 `TransferWithAuthorization` ≈ transfer,
        EIP-2612 `Permit` ≈ approve), so this grants full authority over the EVM
        address's float (bounded to what you bridge there — the NEAR-intents
        balance is never exposed to any EVM signature). `raw_tx` (default false)
        is a SEPARATE kill-switch for arbitrary raw transactions; it does NOT
        contain typed-data drains.
      properties:
        allowed:
          type: boolean
          description: Master on/off for EVM signing. Default false (opt in with true).
        raw_tx:
          type: boolean
          description: Permit signing arbitrary raw EVM transactions. Default false.

    SolanaSignCapability:
      type: object
      description: >-
        `solana_sign` — Solana signing (off-chain messages / transaction
        messages). **Default-DENY under a policy** (same model as `evm_sign`) —
        set `allowed: true` to permit. A wallet with no policy is unrestricted.
        CAVEAT: a signed Solana transaction message is itself fund-moving, so
        `raw_tx` grants full authority over the Solana address's float (bounded
        to what you send there — the NEAR-intents balance is never exposed to
        any Solana signature). The base flag covers message signing only; the
        service rejects "message" bytes that parse as a valid transaction
        message, so the message endpoint cannot bypass `raw_tx`.
      properties:
        allowed:
          type: boolean
          description: Master on/off for Solana signing. Default false (opt in with true).
        raw_tx:
          type: boolean
          description: Permit signing Solana transaction messages. Default false.

    Capabilities:
      type: object
      description: |
        Default-DENY opt-ins for the non-Built primitives, stored alongside
        `rules` / `approval` in the encrypted policy. Every capability defaults to
        DENY under a policy **except** `sign_message` (default-allow). A wallet
        with no policy at all is unrestricted, **except `intents_call`**, which
        stays denied without a policy too.
      properties:
        raw_sign:
          $ref: '#/components/schemas/RawSignCapability'
        confidential:
          $ref: '#/components/schemas/Capability'
        swap:
          $ref: '#/components/schemas/Capability'
        cross_chain_withdraw:
          $ref: '#/components/schemas/Capability'
        limit_order:
          $ref: '#/components/schemas/Capability'
        payment_check:
          $ref: '#/components/schemas/Capability'
        sign_message:
          $ref: '#/components/schemas/SignMessageCapability'
        evm_sign:
          $ref: '#/components/schemas/EvmSignCapability'
        solana_sign:
          $ref: '#/components/schemas/SolanaSignCapability'
        intents_call:
          allOf:
            - $ref: '#/components/schemas/Capability'
          description: >-
            A `call` whose receiver is the NEAR Intents contract
            (`intents.near`, `intents.far`) — directly, or as a
            `w_execute_extension` promise of the bound account (then the bound
            account's own intents account is at stake). **Default-DENY with or
            without a policy.** The contract treats a transaction from an
            account as the owner of that account's intents account, for 1
            yoctoNEAR: such a call
            can `add_public_key` — a key outside the TEE that signs for the
            intents account permanently, past any later policy, freeze or lock —
            or move any intents balance past the transaction types, the address
            list and the per-token limits (`ft_withdraw`, `mt_transfer`). Every
            intents operation has its own endpoint (`/wallet/v1/intents/*`);
            set `allowed: true` only to hand the agent the intents account
            itself. `call` must be permitted as well.

    EvmSignTypedDataRequest:
      type: object
      required: [chain, typed_data]
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
        sub_path:
          $ref: '#/components/schemas/SubPath'
        typed_data:
          type: object
          description: >-
            Standard EIP-712 v4 object (as `eth_signTypedData_v4`):
            `{ domain, types, primaryType, message }`. Arbitrary struct types are
            supported (incl. EIP-3009 `TransferWithAuthorization` and EIP-2612
            `Permit`). The digest is computed server-side — no client-supplied
            hash is trusted.

    EvmSignMessageRequest:
      type: object
      required: [chain, message]
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
        sub_path:
          $ref: '#/components/schemas/SubPath'
        message:
          type: string
          description: >-
            The message to sign under EIP-191 `personal_sign`, interpreted per
            `encoding`.
        encoding:
          type: string
          enum: [utf8, hex]
          default: utf8
          description: >-
            How to interpret `message`. `utf8` (default) signs its UTF-8 bytes
            (matches viem `hashMessage(string)` / MetaMask `personal_sign`);
            `hex` treats `message` as hex (`0x`-prefixed or bare) and signs the
            decoded bytes (viem `hashMessage({ raw })`). No content sniffing —
            malformed hex is rejected.

    EvmSignTransactionRequest:
      type: object
      required: [chain, unsigned_tx]
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
        sub_path:
          $ref: '#/components/schemas/SubPath'
        unsigned_tx:
          type: string
          description: >-
            Serialized unsigned transaction, `0x`-hex (e.g. viem
            `serializeTransaction(tx)`). The service keccak256-hashes and signs
            it — it does not parse, assemble, or broadcast the transaction.

    EvmSignResponse:
      type: object
      required: [signature, chain, wallet_id]
      properties:
        signature:
          type: string
          description: >-
            65-byte recoverable EVM signature, `0x`-hex (`r‖s‖v`, `v ∈ {27,28}`,
            low-s). `ecrecover` over the signed digest returns the wallet's EVM
            address — or, when `sub_path` was given, that sub-key's address
            from `GET /wallet/v1/address?chain=<evm>&sub_path=<same>`.
        sub_path:
          $ref: '#/components/schemas/SubPath'
        chain:
          $ref: '#/components/schemas/Chain'
        wallet_id:
          type: string

    SolanaSignMessageRequest:
      type: object
      required: [chain, message]
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
        message:
          type: string
          description: >-
            The message to sign, interpreted per `encoding`. The decoded bytes
            are signed as-is; bytes that parse as a valid Solana transaction
            message are rejected (use `/wallet/v1/solana/sign-transaction`).
        encoding:
          type: string
          enum: [utf8, hex, base64]
          default: utf8
          description: >-
            How to interpret `message`. `utf8` (default) signs its UTF-8 bytes;
            `hex` (`0x`-prefixed or bare) / `base64` decode `message` first and
            sign the decoded bytes. No content sniffing — malformed input is
            rejected.

    SolanaSignTransactionRequest:
      type: object
      required: [chain, unsigned_tx]
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
        unsigned_tx:
          type: string
          description: >-
            Serialized unsigned transaction **message**, base64 (what the
            signature covers: web3.js `tx.serializeMessage()` /
            `versionedTx.message.serialize()`; max 1232 bytes — the Solana
            packet limit). The service signs the bytes as-is — it does not
            parse, assemble, or broadcast the transaction.

    SolanaSignResponse:
      type: object
      required: [signature, chain, wallet_id]
      properties:
        signature:
          type: string
          description: >-
            64-byte ed25519 signature, base58 (Solana convention). Verifies
            against the wallet's Solana address (its base58 ed25519 public key)
            over the exact submitted bytes.
        chain:
          $ref: '#/components/schemas/Chain'
        wallet_id:
          type: string

    PolicyResponse:
      type: object
      required: [wallet_id, controller, frozen]
      properties:
        wallet_id:
          type: string
        controller:
          type: string
          description: NEAR account that owns the policy.
        frozen:
          type: boolean
        version:
          type: integer
          format: int64
          description: >-
            The policy's version on chain; the next `store_wallet_policy`
            carries this plus one. `0` for a policy stored before versions.
            Absent when the chain could not be read.
        locked:
          type: boolean
          description: >-
            Whether the next policy write and the delete need the approvers'
            quorum (`approval.locked` of the stored policy, as the contract
            holds it). Absent when the chain could not be read.
        policy:
          type: string
          enum: [none, stored]
          description: |
            Whether the wallet has a policy at all. `none`: no policy is
            stored — every operation is allowed (the engine's own rules,
            which no policy relaxes, still hold: account-control operations
            on the extension door are refused for every wallet). `stored`:
            a policy exists and `rules`, `approval`, `capabilities` and
            `authorized_key_hashes` are it, as written — every capability
            it does not name is at that capability's default, which is DENY
            for all but `sign_message`. Absent when the coordinator could not
            read the chain or decrypt what it holds. This is a statement of
            presence, not a rendering of what the policy permits; the
            keystore's evaluator decides that.
        rules:
          $ref: '#/components/schemas/PolicyRules'
        approval:
          $ref: '#/components/schemas/ApprovalConfig'
        capabilities:
          $ref: '#/components/schemas/Capabilities'
        authorized_key_hashes:
          type: array
          items:
            type: string
        refund_addresses:
          $ref: '#/components/schemas/RefundAddresses'
        usage:
          type: object
          additionalProperties: {}
          description: |
            Current accumulated usage per token, per period — spent amounts
            from the coordinator's counters, present whether or not a policy
            is stored. Same shape as `PolicyLimits` — used for client-side
            velocity-limit visualization.

    EncryptPolicyRequest:
      type: object
      required: [wallet_id, rules]
      properties:
        wallet_id:
          type: string
        rules:
          $ref: '#/components/schemas/PolicyRules'
        approval:
          $ref: '#/components/schemas/ApprovalConfig'
        capabilities:
          $ref: '#/components/schemas/Capabilities'
        webhook_url:
          type: string
          format: uri
        authorized_key_hashes:
          type: array
          items:
            type: string
        refund_addresses:
          $ref: '#/components/schemas/RefundAddresses'

    RefundAddresses:
      type: object
      description: |-
        Where a failed cross-chain deposit refunds, per source chain: the
        chain name as the deposit endpoints accept it (`hypercore`, `base`,
        `solana`, …; stored canonical) → an address on that chain. Each
        address is format-checked for its chain when the policy is encrypted,
        and a chain the deposit endpoints do not accept is refused. A chain
        without an entry refunds to the wallet's own derived address on it
        (NEAR, Solana, EVM chains, HyperCore), and the deposit request's
        `refund_address` is ignored — the owner decides where a refund lands,
        not the caller. On a chain the wallet has no address of its own on
        (Bitcoin, Zcash, Tron, …) and no entry names, the request's
        `refund_address` is used, and a deposit without one is refused.
      additionalProperties:
        type: string
      example:
        hypercore: '0x582290c0b2Cb60989B35FFF66049f3e3247355bc'
        solana: 5AmGa2Bcfajbytg55UUb4vCAAzKBMYKZNQwx5S2BH2qf

    EncryptPolicyResponse:
      type: object
      required: [encrypted_base64, wallet_pubkey, policy_hash]
      properties:
        encrypted_base64:
          type: string
        wallet_pubkey:
          type: string
        policy_hash:
          type: string
          description: >-
            sha256 (hex) of the canonical plaintext that was encrypted — every
            object's keys sorted, compact — which a locked policy's approvers
            vote on inside the `policy_update` operation.

    SignPolicyRequest:
      type: object
      required: [encrypted_data, caller]
      properties:
        encrypted_data:
          type: string
        caller:
          type: string
          description: |
            The NEAR account that will send `store_wallet_policy`. Signed, so
            the signature is usable by that account only.

    SignPolicyResponse:
      description: >-
        The signature, or — when the policy on chain is locked — the approval
        the write waits on. Told apart by `status`: a signature has none.
      oneOf:
        - $ref: '#/components/schemas/SignedPolicy'
        - $ref: '#/components/schemas/PolicyUpdatePending'

    SignedPolicy:
      type: object
      required: [signature_hex, public_key_hex, version, locked, valid_until, policy_hash]
      properties:
        signature_hex:
          type: string
        public_key_hex:
          type: string
        version:
          type: integer
          format: int64
          description: >-
            What `store_wallet_policy` must be called with: the chain's version
            plus one. Inside the signature.
        locked:
          type: boolean
          description: >-
            The new policy's `approval.locked`, as the keystore read it from
            the plaintext. `store_wallet_policy` must be called with exactly
            this; it is inside the signature.
        valid_until:
          type: integer
          format: int64
          description: >-
            Unix seconds after which the contract refuses this signature —
            seven days from signing. `store_wallet_policy` must be called with
            exactly this; it is inside the signature.
        policy_hash:
          type: string
          description: sha256 (hex) of the new policy's canonical plaintext.
        request_hash:
          type: string
          description: >-
            The `policy_update` hash the approvers' votes were verified over.
            Present only when the policy on chain was locked.

    PolicyUpdatePending:
      type: object
      required: [status, approval_id, request_id, request_hash, required_approvals, request_data]
      properties:
        status:
          type: string
          enum: [pending_approval]
        approval_id:
          type: string
          format: uuid
        request_id:
          type: string
          format: uuid
          description: >-
            Where the signature appears once the threshold is met:
            `GET /wallet/v1/requests/{request_id}` → `status: success`,
            `result` = `{wallet_signature, public_key_hex, wallet_pubkey,
            version, locked, valid_until, policy_hash, request_hash,
            encrypted_data, caller}`. `status: failed` with `result.error` when the
            keystore refused the votes or the policy moved on.
        request_hash:
          type: string
          description: >-
            The `policy_update` operation hash the approvers sign (see
            `Nep413Auth`): `{wallet_pubkey, policy_hash, version, locked,
            caller}`, canonical.
        required_approvals:
          type: integer
        request_data:
          type: object
          additionalProperties: {}
          description: >-
            What the approvers are approving: `policy` (the new policy's
            plaintext, as it will be stored), `policy_hash`, `version`,
            `locked`, `caller`, `wallet_pubkey`, `encrypted_data`.

    InvalidateCacheRequest:
      type: object
      required: [wallet_id]
      properties:
        wallet_id:
          type: string

    # ----- Approvals -----
    PendingApproval:
      type: object
      required: [approval_id, type, request_data, request_hash, decision, required, approved, expires_at]
      properties:
        approval_id:
          type: string
          format: uuid
        request_id:
          type: [string, 'null']
          format: uuid
        type:
          $ref: '#/components/schemas/RequestType'
        request_data:
          type: object
          additionalProperties: {}
        op:
          type: [object, 'null']
          additionalProperties: {}
          description: >-
            Canonical op to RENDER (parsed from the stored canonical JSON). The
            dashboard renders this directly. `null` for legacy rows predating
            canonical-op storage.
        decoded_effects:
          type: [object, 'null']
          additionalProperties: {}
          description: >-
            Present ONLY for a `w_execute_extension` op (Agent Connect's
            extension door), whose own fields describe nothing: the destination
            is the agent's own account and the deposit is a mandated 1-yocto
            marker, while every real recipient and amount is nested in
            `args_base64`. This is those contents, decoded from the same bytes
            `request_hash` covers — an approver renders it INSTEAD of guessing
            from `op`. Absent for every other operation, which states its
            effects in its own fields.


            Shape: `native_total` (yocto, decimal string), `action_count`,
            `promises[]` (`index`, `receiver`, `refund_to`, `native`),
            `token_moves[]` (`promise`, `method`, `token`, `recipient`,
            `amount`, `unit` = `token_units` | `token_id`),
            `storage_registrations[]`, plus `internal_ops[]` and
            `unstatable_calls[]` — the last two are refused before an approval
            can exist and are rendered only so their presence could never be
            silent.
        request_hash:
          type: string
          description: >-
            Canonical request hash to SIGN — approvers sign
            `approve:{approval_id}:{wallet_pubkey}:{request_hash}` (see
            `Nep413Auth`), or have their wallet contract resolve it (see
            `ContractVoteAuth`).
        decision:
          type: string
          description: Always `requires_approval` for a pending row.
          enum: [requires_approval]
        required:
          type: integer
        approved:
          type: integer
          description: Approve votes so far. Reject votes are not counted toward the threshold.
        expires_at:
          type: string
          format: date-time

    PendingApprovalsResponse:
      type: object
      required: [approvals]
      properties:
        approvals:
          type: array
          items:
            $ref: '#/components/schemas/PendingApproval'

    ApprovalDetail:
      type: object
      description: >-
        Public, read-only detail for one pending approval (`getApprovalDetail`).
        Returns only non-sensitive metadata. `wallet_pubkey` + `request_hash` are
        what an approver binds into its vote (see `Nep413Auth` and
        `ContractVoteAuth`); the
        dashboard renders `op`.
      required:
        - id
        - wallet_id
        - request_type
        - request_data
        - status
        - required_approvals
        - request_hash
        - wallet_pubkey
        - expires_at
        - created_at
        - approvers
      properties:
        id:
          type: string
          format: uuid
        wallet_id:
          type: string
        request_type:
          $ref: '#/components/schemas/RequestType'
        request_data:
          type: object
          additionalProperties: {}
        status:
          type: string
          enum: [pending, approved, rejected, expired]
        required_approvals:
          type: integer
        request_hash:
          type: string
        op:
          type: [object, 'null']
          additionalProperties: {}
          description: Canonical op for the dashboard to render. `null` for legacy rows.
        decoded_effects:
          type: [object, 'null']
          additionalProperties: {}
          description: >-
            What a `w_execute_extension` op actually moves, decoded from the
            same bytes `request_hash` covers — see `PendingApproval` for the
            shape and for why rendering `op` alone would show an approver
            nothing about the money. `null` for every other operation.
        wallet_pubkey:
          type: string
          description: On-chain wallet pubkey bound into the approve/reject vote message.
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        approvers:
          type: array
          description: Signatures collected so far.
          items:
            type: object
            required: [approver_id, approver_role, signature, proof_kind, created_at]
            properties:
              approver_id:
                type: string
              approver_role:
                type: string
                description: '`signer` for an approve vote, `reject` for a reject vote.'
              signature:
                type: [string, 'null']
                description: The NEP-413 signature; null for a contract-wallet vote.
              proof_kind:
                type: string
                enum: [nep413, contract]
                description: How the vote was proven — a key signature, or the approver's wallet contract.
              created_at:
                type: string
                format: date-time

    Nep413Auth:
      type: object
      description: |
        NEP-413 signed authentication payload. The signed message binds the
        wallet's on-chain pubkey so a vote can't be replayed onto another wallet:
        `approve:{approval_id}:{wallet_pubkey}:{request_hash}` for approve, or
        `reject:{approval_id}:{wallet_pubkey}:{request_hash}` for reject. The
        `wallet_pubkey` and `request_hash` come from `getApprovalDetail` (or
        `listPendingApprovals`). `recipient` for the NEP-413 signature is the
        wallet contract id.
      required: [signature, public_key, account_id, nonce]
      properties:
        signature:
          type: string
        public_key:
          type: string
        account_id:
          type: string
        nonce:
          type: string

    ContractVoteAuth:
      type: object
      description: |
        A vote from an approver without access keys: a NEP-616 wallet contract
        owned by an EVM key or a passkey. `authorization` is the blob the
        approver's wallet resolves, sent verbatim; its payload must be the same
        string a key holder signs, `approve:{approval_id}:{wallet_pubkey}:{request_hash}`
        or `reject:{approval_id}:{wallet_pubkey}:{request_hash}`.

        Accepted only from an account running a wallet build this deployment
        lists. The coordinator calls `w_is_signature_allowed` and
        `w_resolve_auth` on `account_id` at one block before storing the vote,
        and the keystore does again before signing. EIP-712 wallets resolve
        with `{purpose: "PROVE_OWNERSHIP", recipient, authorization}`, where
        `recipient` is this deployment's contract id (`outlayer.near` on
        mainnet, `outlayer.testnet` on testnet). Passkey (NEP-641) wallets
        resolve with `{path: [], authorization}`; an authorization that leaves
        sub-authorizations pending is refused. A passkey message timestamped in
        the future is refused by the wallet itself; sign with a timestamp a
        little in the past.
      required: [account_id, authorization]
      properties:
        account_id:
          type: string
        authorization:
          type: string
          maxLength: 8192

    ApproveRequest:
      description: Exactly one proof. Both, or neither, is a 400.
      oneOf:
        - $ref: '#/components/schemas/Nep413Auth'
        - $ref: '#/components/schemas/ContractVoteAuth'

    RejectRequest:
      description: Exactly one proof, and an optional reason. Both proofs, or neither, is a 400.
      oneOf:
        - allOf:
            - $ref: '#/components/schemas/Nep413Auth'
            - type: object
              properties:
                reason:
                  type: string
        - allOf:
            - $ref: '#/components/schemas/ContractVoteAuth'
            - type: object
              properties:
                reason:
                  type: string

    ApproveResponse:
      type: object
      required: [approval_id, status, approved, required]
      properties:
        approval_id:
          type: string
          format: uuid
        status:
          type: string
          enum: [pending, approved, rejected, expired]
        approved:
          type: integer
          description: Approve votes so far. Reject votes are not counted toward the threshold.
        required:
          type: integer
        request_id:
          type: [string, 'null']
          format: uuid

    RejectResponse:
      type: object
      required: [approval_id, status]
      properties:
        approval_id:
          type: string
          format: uuid
        status:
          type: string
          description: >-
            `rejected` — the reject came from a REAL policy approver, so the request is
            cancelled (a real reject vetoes it irrevocably). `reject_vote_recorded` — the
            signer is not a configured approver: the vote is stored and the request stays
            `pending_approval` (the keystore still vetoes execution at sign time).
          enum: [rejected, reject_vote_recorded]

    # ----- Audit & requests -----
    AuditEvent:
      type: object
      required: [type, details, at]
      properties:
        type:
          type: string
        request_id:
          type: [string, 'null']
        status:
          type: [string, 'null']
        details:
          type: object
          additionalProperties: {}
        at:
          type: string
          format: date-time

    AuditResponse:
      type: object
      required: [events]
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/AuditEvent'

    RequestStatusResponse:
      type: object
      required: [request_id, type, status, created_at]
      properties:
        request_id:
          type: string
          format: uuid
        type:
          $ref: '#/components/schemas/RequestType'
        status:
          $ref: '#/components/schemas/RequestStatus'
        result:
          description: |-
            Operation-specific result payload, present once `status` is
            `success` (otherwise `null` or an `{ "error": "<reason>" }` object
            on `failed`). The shape depends on `type`:

            - `type = "withdraw"` — conforms to
              [`WithdrawResult`](#/components/schemas/WithdrawResult).
            - Cross-chain withdraws (`intents_cross_chain_withdraw`) and
              gasless swaps additionally carry a nullable
              `destination_tx_hash` — the real delivery transaction on the
              destination chain (safe to render as an explorer link on the
              requested chain). `null` until the 1Click bridge settles; the
              lazy on-read refresh fills it in, and the `request_completed`
              webhook carries it. All other identifier fields
              (`transfer_intent_hash`, `intent_hash`) are NEAR-Intents
              hashes, NOT destination-chain transactions.
            - Withdraws and swaps: `settled_late: true` marks a request whose
              outcome was settled from the chain after its response came
              back `processing`. A `failed` request carrying
              `never_executed: true` or `never_submitted: true` moved no
              funds and is safe to retry under a new idempotency key. A
              `failed` one without them may have moved funds — a bridge
              that failed or refunded (`result.reason`), or a NEAR
              transaction that failed on chain after its gas was spent —
              so reconcile the balance before acting again.
            - Other request types are not yet schema-documented; treat the
              object as opaque until added in a later spec release.

            Uses `anyOf` (not `oneOf`) deliberately — `WithdrawResult` is also
            a valid `object`, and `oneOf` would require exactly one match,
            so a successful withdraw would fail strict validators.
          anyOf:
            - $ref: '#/components/schemas/WithdrawResult'
            - type: 'null'
            - type: object
              additionalProperties: {}
        created_at:
          type: string
          format: date-time
        updated_at:
          type: [string, 'null']
          format: date-time

    WithdrawResult:
      type: object
      description: |-
        Result payload for a successful `withdraw` request — what the
        recipient actually received on-chain. Emitted in the `result` field of
        `GET /wallet/v1/requests/{id}` and in the `result` field of the
        `request_completed` webhook for withdraw requests.
      required: [intent_hash, delivered]
      properties:
        intent_hash:
          type: string
          description: |-
            Base58-encoded NEAR Intents hash returned by `solver-relay`.
            Empty string if the relay did not return one — the field is
            always present so clients can index it without `Option` handling.
          example: 4GArqMi1WJwsw7p4tWHAbYG2Se5Wp6YSb8Ab3C8cUTJg
        delivered:
          description: |-
            Canonical identifier of the asset the recipient received on-chain.
            Format mirrors the request `token` field of
            `POST /wallet/v1/intents/withdraw`, so clients can compare request
            vs. response directly:

            - `"native_near"` — the wallet emitted a `native_withdraw` intent
              that unwrapped wNEAR and sent native NEAR. The recipient
              received native NEAR regardless of what the request `token`
              field named (`""`, `"near"`, or `"native"`).
            - `"nep141:<contract>"` — the wallet emitted a NEP-141 `transfer`
              intent. The recipient received that token, including wNEAR
              (`"nep141:wrap.near"`), USDC, USDT, etc.

            Never returned: the legacy short symbol `"wnear"` (was emitted
            in error by coordinator versions prior to the
            `WithdrawResult`-typed response — see api-spec CHANGELOG).
          oneOf:
            - type: string
              const: native_near
            - type: string
              pattern: '^nep141:.+'
              example: 'nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1'

    RequestListResponse:
      type: object
      required: [requests, total]
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/RequestStatusResponse'
        total:
          type: integer

    # ── Confidential intents ──────────────────────────────────────────────
    ConfidentialShieldRequest:
      description: SHIELD body — same shape as `IntentsDepositRequest`.
      allOf:
        - $ref: '#/components/schemas/IntentsDepositRequest'
    ConfidentialUnshieldRequest:
      description: UNSHIELD body — same shape as `IntentsDepositRequest`.
      allOf:
        - $ref: '#/components/schemas/IntentsDepositRequest'
    ConfidentialWithdrawRequest:
      description: >-
        Confidential withdraw body — same shape as `WithdrawRequest`; `token`
        is required (the source confidential asset to deliver). `chain` is the
        token's home chain, `"near"`, or another chain that lists the same
        symbol (delivered as that listing, swapped on the way).
        `chain="near"` delivers native NEAR for `nep141:wrap.near` (via
        `intents.near native_withdraw`) and the NEP-141 token on NEAR for omft
        bridge assets (use `confidentialUnshield` if you want to send to your
        own public balance instead).
      allOf:
        - $ref: '#/components/schemas/WithdrawRequest'
    ConfidentialSwapRequest:
      description: >-
        Confidential swap body — same shape as `SwapRequest`
        (`token_in` / `amount_in` / `token_out` / optional `min_amount_out`).
        On a multisig wallet the confidential swap binds `token_out` and
        `min_amount_out` into the approved op (like a public swap), so approvers
        commit to the output terms — a compromised coordinator cannot change them
        after approval.
      allOf:
        - $ref: '#/components/schemas/SwapRequest'
    ConfidentialDepositIntentRequest:
      description: |-
        Cross-chain deposit body — the same two shapes as
        `DepositIntentRequest` (`source_asset` or `chain`+`token`), with the
        confidential route's own `destination_asset` rule: what lands in the
        confidential balance is `destination_asset` when given; otherwise USDC
        from any chain lands as NEAR USDC (as on the public route), and any
        other token lands as the SAME asset, bridged — see
        [`ConfidentialDestinationAsset`](#/components/schemas/ConfidentialDestinationAsset).

        A failed bridge refunds into the confidential balance (the wallet's
        64-hex intentsUserId), except from `hypercore`, whose assets refund
        only on their origin chain. There the refund address follows the same
        rule as the public route — the wallet policy's `refund_addresses`
        entry for `hypercore`; a policy without one → the wallet's derived
        HyperCore address (the request's `refund_address` is ignored); no
        policy → `refund_address`, else the derived address. HyperCore always
        has a derived address, so the request's address is never required
        here.
      anyOf:
        - title: BySourceAsset
          type: object
          required: [source_asset, amount]
          properties:
            source_asset:
              $ref: '#/components/schemas/DepositIntentSourceAsset'
            destination_asset:
              $ref: '#/components/schemas/ConfidentialDestinationAsset'
            amount:
              $ref: '#/components/schemas/DepositIntentAmount'
            refund_address:
              $ref: '#/components/schemas/DepositRefundAddress'
        - title: ByChainAndToken
          type: object
          required: [chain, amount]
          properties:
            chain:
              $ref: '#/components/schemas/DepositIntentChain'
            token:
              $ref: '#/components/schemas/DepositIntentToken'
            destination_asset:
              $ref: '#/components/schemas/ConfidentialDestinationAsset'
            amount:
              $ref: '#/components/schemas/DepositIntentAmount'
            refund_address:
              $ref: '#/components/schemas/DepositRefundAddress'
    ConfidentialDepositIntentResponse:
      description: |-
        Cross-chain deposit address — the fields of `DepositIntentResponse`,
        with `amount_out` / `min_amount_out` ABSENT when the confidential
        upstream states none for the route (it does for some same-asset
        deposits). They are never substituted with `amount`, which is in the
        origin asset's units.
      allOf:
        - $ref: '#/components/schemas/DepositIntentResponseFields'

    ConfidentialTransferRequest:
      type: object
      description: >-
        Private confidential→confidential transfer. No `chain` (NEAR-only
        context); `token` required (no native-asset concept inside the
        confidential shard).
      required: [to, amount, token]
      properties:
        to:
          type: string
          description: Recipient NEAR account id (intentsUserId / 64-hex implicit account).
        amount:
          type: string
          description: Amount in minimal units.
        token:
          type: string
          description: Defuse asset id, e.g. `nep141:wrap.near`.

    ConfidentialOpResponse:
      type: object
      description: |
        Result of a confidential shield / unshield / withdraw / transfer / swap.
        The op is asynchronous — the user's signed intent settles on the private
        shard (`intents.far`, no public RPC), so there is no public `tx_hash`;
        track via `intent_hash` / `deposit_address` and poll
        `GET /wallet/v1/requests/{id}`.

        Once the op is terminal, the request row's `result.swap_details`
        carries `intentHashes`, `nearTxHashes`, `originChainTxHashes` and
        `destinationChainTxHashes` — **all arrays of plain hash strings**,
        with 1Click-style **camelCase** inner keys (the `swap_details`
        container itself is snake_case). Upstream 1Click emits
        `{hash, explorerUrl}` objects; the coordinator normalizes them to
        plain strings, so this wire shape is stable regardless of upstream
        changes. Also present: settled amounts and refund fields
        (`amountIn`, `amountOut`, `refundedAmount`, `refundReason`, …). For
        an external-chain `confidentialWithdraw`, `destinationChainTxHashes`
        holds the actual delivery transaction on the destination chain; the
        arrays are empty until settlement and may stay empty for
        shard-internal ops (shield / unshield / transfer / swap).

        **Multisig:** the Trusted confidential ops (withdraw / transfer / swap)
        are subject to the wallet's approval policy. When approval is required the
        response inlines `approval_id` / `required` / `approved` / `request_hash`
        (same shape as `WithdrawResponse` / `SwapResponse`) — sign `request_hash`
        and submit your approval vote; the op executes after the threshold is met.
      required: [request_id, status]
      properties:
        request_id:
          type: string
          format: uuid
        status:
          type: string
          description: >-
            Normalized lifecycle status (1Click's UPPERCASE state machine mapped
            to lowercase): `pending_deposit` → `processing` → `success` /
            `failed` / `refunded`. `pending_approval` is returned instead when a
            multisig wallet must approve the op first. The raw upstream status is
            in the request row's `result.oneclick_status`. A call answers
            `processing` with a `poll_url` when the intent was submitted and the
            upstream's answer was lost: the intent may have been taken, so do not
            retry — the request settles on its own.
          enum: [pending_deposit, processing, success, failed, refunded, pending_approval]
        intent_hash:
          type: [string, 'null']
          description: Confidential-shard intent hash (never appears on the public chain).
        deposit_address:
          type: [string, 'null']
          description: Opaque 1Click hop address — the status primary key.
        approval_id:
          type: string
          format: uuid
          description: Present only on `pending_approval` (multisig) — the approval to vote on.
        required:
          type: integer
          description: Present only on `pending_approval` — approvals needed.
        approved:
          type: integer
          description: Present only on `pending_approval` — approvals collected so far (0 at creation).
        request_hash:
          type: string
          description: Present only on `pending_approval` — sha256(canonical_json(op)); sign this to approve.
        poll_url:
          type: string
          description: Present with `status=processing` — `GET /wallet/v1/requests/{request_id}`.

    ConfidentialBalanceResponse:
      type: object
      description: A single confidential balance (response to `?token=`).
      required: [balance, token, account_id]
      properties:
        balance:
          type: string
          description: Minimal units; `"0"` if the wallet holds none of this asset.
        token:
          type: string
        account_id:
          type: string
          description: Wallet's 64-hex NEAR implicit account (intentsUserId).

    ConfidentialBalanceEntry:
      type: object
      required: [token, balance]
      properties:
        token:
          type: string
        balance:
          type: string

    ConfidentialBalancesResponse:
      type: object
      description: All confidential balances (response when `token` is omitted).
      required: [balances, account_id]
      properties:
        balances:
          type: array
          items:
            $ref: '#/components/schemas/ConfidentialBalanceEntry'
        account_id:
          type: string