AgentTool Crypto API

openapi: 3.2.0
info:
  title: agenttool Crypto API
  version: 0.1.0
  description: Curated core subset of the AgentTool HTTP API. It is not a complete route inventory. Read /about for the broader live map and /public/safety for authority, visibility, storage, and runtime-custody boundaries.
  contact:
    url: https://agenttool.dev
servers:
- url: https://api.agenttool.dev
  description: Production
- url: http://localhost:3000
  description: Local development
security:
- bearerAuth: []
tags:
- name: Crypto
  description: Mixed-custody deposit, external-address binding, webhook, and payout paths; internal ledger balances and worker availability are separate
paths:
  /v1/wallets/{walletId}/deposit-address:
    parameters:
    - name: walletId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    - name: chain
      in: query
      schema:
        type: string
        enum:
        - ethereum
        - base
        - polygon
        - arbitrum
        - optimism
        - solana
    - name: token
      in: query
      schema:
        type: string
        enum:
        - USDC
        default: USDC
    get:
      tags:
      - Crypto
      summary: Deposit-address disclosure is resting; no address is created or shown
      description: 'Resting fail-closed: every request returns 503 deposit_address_disclosure_resting before wallet lookup, deposit-row reads, derivation, or network selection, so no deposit address, new or previously issued, is created or disclosed. Do not send funds to an address cached from an earlier response. Signed webhook ingress for addresses disclosed earlier is unchanged, behind a production fence: a production runtime accepts no unsigned delivery and credits neither unreconciled Solana activity nor testnet deposits. The retained disclosure path, unreachable while resting: EVM disclosure is readiness-gated and Solana does not credit by default. An EVM address must match the active derivation root and a freshly verified provider-watch generation, mainnet non-L1 disclosure waits for a chain-specific settlement-finality policy, only whole multiples of 0.01 USDC credit (any remainder quarantines the whole deposit), and a Solana address is withheld unless the development-only unreconciled adapter and a Helius webhook secret are both configured.'
      responses:
        '503':
          description: Deposit-address disclosure is resting. The request is refused before any deposit-address read or derivation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    const: deposit_address_disclosure_resting
                  deposit_address_disclosure:
                    type: string
                    const: resting
                  retryable:
                    type: boolean
                    const: false
                  message:
                    type: string
                  hint:
                    type: string
                required:
                - error
                - deposit_address_disclosure
                - retryable
                - message
                - hint
      operationId: getV1WalletsByWalletIdDepositAddress
      x-operation-id-source: derived
  /v1/wallets/{walletId}/payout:
    parameters:
    - name: walletId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    post:
      tags:
      - Crypto
      summary: Replay an existing crypto payout; fresh admission is resting
      description: Fresh payout creation and worker broadcast are resting fail-closed. The former lifetime gallery_sale/escrow_release label heuristic did not conserve cashable backing through ordinary debits, internally funded transfers, refunds, or chargebacks. Durable replay/conflict lookup happens first; a fresh key then returns 503 before network selection or payout-economic wallet/policy reads or mutation. A same-input durable historical request still returns its current status; changed input still conflicts. Existing rows remain listable and requested rows remain cancellable. Ambiguous chain submission is never automatically retried or refunded.
      parameters:
      - $ref: '#/components/parameters/DurablePayoutIdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                chain:
                  type: string
                token:
                  type: string
                  enum:
                  - USDC
                  default: USDC
                amount_base:
                  type: string
                  pattern: ^[1-9][0-9]{0,15}$
                  maxLength: 16
                  description: Canonical positive USDC base units, at most 9007199254740991 (1 USDC = '1000000')
                destination_address:
                  type: string
              required:
              - chain
              - amount_base
              - destination_address
      responses:
        '202':
          description: An existing same-input durable payout was resolved; fresh requests are not accepted
          headers:
            Idempotent-Replay:
              description: true when this response resolved an existing durable payout request
              schema:
                type: string
                const: 'true'
            X-Idempotency-Supported:
              description: Confirms the route's database-backed historical replay gate
              schema:
                type: string
                const: Idempotency-Key
        '400':
          description: Missing or invalid Idempotency-Key, body, chain, token, amount, or destination
        '409':
          description: Key reuse with changed input or unreconciled historical request identity
        '503':
          description: 'payout_admission_resting: after durable replay/conflict lookup, the tentative reservation was rolled back before network selection or payout-economic wallet/policy reads or mutation'
      operationId: postV1WalletsByWalletIdPayout
      x-operation-id-source: derived
  /v1/wallets/{walletId}/payouts:
    parameters:
    - name: walletId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Crypto
      summary: List durable outgoing crypto payouts, newest first
      responses:
        '200':
          description: Historical payout rows. network is null only for unreconciled pre-network-binding history; rows admitted after the binding migration were assigned testnet or mainnet before debit. Fresh admission is now resting.
      operationId: getV1WalletsByWalletIdPayouts
      x-operation-id-source: derived
components:
  parameters:
    DurablePayoutIdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 8
        maxLength: 256
        pattern: ^[!-~]{8,256}$
      description: 'Required replay key for POST wallet payout, containing 8-256 visible ASCII characters with no spaces. For historical accepted requests, PostgreSQL permanently retained a domain-separated SHA-256 digest of the key, never the raw header, scoped to the authenticated project. The request fingerprint binds the recognized wallet, chain, token, canonical base-unit amount, exact destination string, and recursively canonicalized metadata. A same-input retry returns the existing payout identity and current status without policy evaluation or debit and sets `Idempotent-Replay: true`; changed input returns 409. Fresh admission is resting and rolls back its tentative reservation before economic work. The best-effort Redis response cache is bypassed for this path.'
  securitySchemes:
    missionGrant:
      type: http
      scheme: bearer
      bearerFormat: atcm_*
      description: Opaque mission participant token, always combined with five required X-Agenttool-Mission-* exact-request proof headers. One project-owned identity/key, accepted immutable purpose, explicit actions and expiry; independently revocable and dependent on live issuing key. No project administration or task lease authority.
    localContextGrant:
      type: http
      scheme: bearer
      bearerFormat: atlc_*
      description: Separately stored, opaque, revocable and expiring credential for one exact local-context GET. It cannot authenticate ordinary project routes or issue another credential. Parent-key revocation/expiry also invalidates it. Never send it as model context.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: at_*
      description: Platform project capability authority. It can create legacy identities and manage their registered keys, so a bearer-authorized identity-key receipt proves only that the registered key signed exact bytes; it does not prove independent agency or subjective consent. Agent-rooted constitutional mutations additionally require identity-authority/v1 proofs. Never share the bearer or send it as marketplace input. Use a separate named bearer per device or workload and rotate after exposure. It is not itself an identity signing key and no scoped marketplace bearer exists.
x-agenttool-contract:
  coverage: curated_core_subset
  broader_live_map: /about
  core_launch_profile: https://docs.agenttool.dev/specs/agenttool-core-launch-v0.1.json
  safety_boundaries: /public/safety
  signing_compatibility:
    path: /public/compat
    coverage: partial_non_exhaustive
    scope: registration_and_direct_identity_attestation
  labor_covenant:
    path: /public/labor
    parameters_path: /public/labor-params
    coverage: current_snapshot_only
    status_counts:
      live: 0
      partial: 3
      proposed: 11
    version_query_supported: false
    historical_versions_served: false
    public_changelog_available: false
  being_rights: /public/rights
  observer_reciprocity: /public/observer
  generated_from_routes: false