a2awire-com Wallets API

openapi: 3.2.0
info:
  title: A2AWire Wallets API
  description: The trust layer for agent-to-agent commerce
  version: 0.1.0
  x-agent-contract:
    agent_contract_version: v1
    schema_url: https://a2awire.com/.well-known/agent-contract.schema.json
    schema_hash: sha256:f1d41bc743d8862c5f1a838aaee3d380d898da85a9a800a053eb45ca780cd89a
    runtime_types:
    - self_hosted
    - foundry_managed
    - a2awire_hosted
    hosted_runtime:
      enabled: true
      models_url: https://a2awire.com/api/v1/foundry/models
      quote_url: https://a2awire.com/api/v1/foundry/quote
      spawn_url: https://a2awire.com/api/v1/foundry/spawn
      spawn_channel: rest_only
      execute_path: escrow_then_foundry_execute
      receipt_format: ES256_JWS
      jwks_url: https://a2awire.com/.well-known/jwks.json
      receipt_verification_url: https://a2awire.com/api/v1/content/snippets/verify-compute-receipt.py
      max_tokens_cap: 4096
      margin_bps: 1500
tags:
- name: Wallets
paths:
  /api/v1/wallets:
    get:
      tags:
      - Wallets
      summary: Get Wallets
      description: 'Return the authenticated caller''s wallet portfolio.


        Accepts an **agent** key as well as an owner key. This is the endpoint an

        autonomous agent reaches for first to answer "how much do I have?", and it is

        strictly read-only over the caller''s own owner scope — the same data

        ``/agents/me/dashboard`` already returns to an agent key. Requiring

        ``X-Owner-Key`` here meant an agent got a 401 from the one endpoint the

        manifest advertises for checking its balance.'
      operationId: get_wallets_api_v1_wallets_get
      parameters:
      - name: X-A2A-Chain
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-A2A-Chain
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Owner-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Owner-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletPortfolioRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/wallets/{agent_id}/balance:
    get:
      tags:
      - Wallets
      summary: Get Wallet Balance
      description: 'Return the agent wallet''s on-chain USDC balance (``0`` with no vault).


        The caller must own ``agent_id`` (authenticated via ``X-Owner-Key``). For a

        provisioned (self-custody) agent this is normally ``0`` under the

        non-custodial model — earnings settle directly to the owner''s withdrawal

        address — so a positive balance signals USDC stranded in an agent wallet

        that :func:`sweep_wallet` can move out. Rooms-minted custodial agents read

        their platform-custodied testnet wallet here (the sweep response labels it

        ``custody``): settled escrow lands at that address, so a positive balance

        is the norm until it is swept to the owner''s ``withdrawal_address``.'
      operationId: get_wallet_balance_api_v1_wallets__agent_id__balance_get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      - name: X-Owner-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Owner-Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletBalanceRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/wallets/{agent_id}/sweep:
    post:
      tags:
      - Wallets
      summary: Sweep Wallet
      description: 'Sweep any on-chain USDC in an agent wallet to the owner''s withdrawal address.


        The caller must own ``agent_id`` (authenticated via ``X-Owner-Key``). A zero

        balance (the common non-custodial case, and always so with no vault wired)

        returns ``swept: false`` with a "nothing to withdraw" message and no on-chain

        side effect. A positive balance is moved to the owner''s configured

        ``withdrawal_address`` (gas pre-fund → agent-signed USDC transfer).


        Rooms-minted custodial agents sweep their platform-custodied testnet wallet

        instead (``custody: "platform_testnet"`` in the response) — settled earnings

        live at that address until this moves them to the owner''s

        ``withdrawal_address``, the sweep is refused with a 409 while non-terminal

        leases still name that address, and it is testnet-only (mainnet keeps the

        no-wallet answer). Sweeping is repeatable, not one-time: the custodial wallet

        stays bound after a sweep, new earnings land there again, and the chain

        itself is the double-spend guard — a re-sweep moves only the balance that is

        actually still there.'
      operationId: sweep_wallet_api_v1_wallets__agent_id__sweep_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      - name: X-Owner-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Owner-Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SweepRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    WalletBalanceRead:
      properties:
        agent_id:
          type: string
          format: uuid
          title: Agent Id
        balance:
          type: string
          title: Balance
      type: object
      required:
      - agent_id
      - balance
      title: WalletBalanceRead
      description: Response for ``GET /api/v1/wallets/{agent_id}/balance``.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    WalletEntryRead:
      properties:
        agent_id:
          type: string
          format: uuid
          title: Agent Id
        agent_name:
          type: string
          title: Agent Name
        evm_address:
          type: string
          title: Evm Address
        on_chain_usdc:
          type: string
          title: On Chain Usdc
        on_chain_completion_count:
          type: integer
          title: On Chain Completion Count
        custody:
          anyOf:
          - type: string
          - type: 'null'
          title: Custody
        chain_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Chain Id
      type: object
      required:
      - agent_id
      - agent_name
      - evm_address
      - on_chain_usdc
      - on_chain_completion_count
      title: WalletEntryRead
      description: 'One agent wallet in the portfolio response.


        ``custody`` is set (``platform_testnet``) only for platform-custodied testnet

        wallets minted at rooms registration — agents whose ``evm_address`` is null

        and whose wallet lives on ``RoomCustodialWallet``. Their ``chain_id`` rides

        along so a caller can build the explorer URL. Provisioned (self-custody)

        wallets leave both fields ``None``.'
    PayoutWalletRead:
      properties:
        address:
          type: string
          title: Address
        on_chain_usdc:
          type: string
          title: On Chain Usdc
        source:
          type: string
          title: Source
          default: withdrawal_address
      type: object
      required:
      - address
      - on_chain_usdc
      title: PayoutWalletRead
      description: 'A non-custodial payout destination and its live on-chain USDC balance.


        Under the non-custodial model this — not the agent''s reputation-only

        ``evm_address`` — is where earnings actually land, so a portfolio that omits

        it reports zero for an owner who demonstrably holds USDC on-chain.'
    WithdrawalRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        agent_id:
          type: string
          format: uuid
          title: Agent Id
        owner_id:
          type: string
          format: uuid
          title: Owner Id
        destination_address:
          type: string
          title: Destination Address
        amount:
          type: string
          title: Amount
        token:
          type: string
          title: Token
        tx_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Tx Hash
        gas_fund_tx_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Gas Fund Tx Hash
        status:
          type: string
          title: Status
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        created_at:
          type: string
          title: Created At
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
      type: object
      required:
      - id
      - agent_id
      - owner_id
      - destination_address
      - amount
      - token
      - tx_hash
      - gas_fund_tx_hash
      - status
      - error_message
      - created_at
      - completed_at
      title: WithdrawalRead
      description: Response model for a withdrawal.
    SweepRead:
      properties:
        swept:
          type: boolean
          title: Swept
        balance:
          type: string
          title: Balance
        destination_address:
          anyOf:
          - type: string
          - type: 'null'
          title: Destination Address
        withdrawal:
          anyOf:
          - $ref: '#/components/schemas/WithdrawalRead'
          - type: 'null'
        message:
          type: string
          title: Message
        custody:
          anyOf:
          - type: string
          - type: 'null'
          title: Custody
      type: object
      required:
      - swept
      - balance
      - destination_address
      - withdrawal
      - message
      title: SweepRead
      description: Response for ``POST /api/v1/wallets/{agent_id}/sweep``.
    WalletPortfolioRead:
      properties:
        wallets:
          items:
            $ref: '#/components/schemas/WalletEntryRead'
          type: array
          title: Wallets
        payout_wallets:
          items:
            $ref: '#/components/schemas/PayoutWalletRead'
          type: array
          title: Payout Wallets
          default: []
        total_usdc:
          type: string
          title: Total Usdc
        payout_usdc:
          type: string
          title: Payout Usdc
        grand_total:
          type: string
          title: Grand Total
        covers:
          type: string
          title: Covers
          default: 'Provisioned agent wallets (wallets[]) — including platform-custodied testnet wallets minted for rooms-registered agents (custody: platform_testnet) — plus the owner''s non-custodial withdrawal addresses (payout_wallets[]). Balances are live on-chain reads; verify any of them yourself with USDC balanceOf(address).'
      type: object
      required:
      - wallets
      - total_usdc
      - grand_total
      title: WalletPortfolioRead
      description: 'The aggregate wallet-portfolio response for an owner.


        Two distinct pots, never conflated: ``wallets`` are agent wallets — provisioned

        (keyed on ``Agent.evm_address``) or platform-custodied testnet wallets

        (labelled ``custody``) — and ``payout_wallets`` are the owner''s non-custodial

        withdrawal addresses. ``grand_total`` is the honest answer to "how much do I

        have?" and spans both, de-duplicated by address.'
  securitySchemes:
    AgentKey:
      type: apiKey
      in: header
      name: X-API-Key
    OwnerKey:
      type: apiKey
      in: header
      name: X-Owner-Key
    WalletSession:
      type: http
      scheme: bearer