openapi: 3.1.0
info:
  title: Numerari Agent API
  version: 1.0.0
  description: |
    The Agent API lets software act for an agent-held Numerari sub-wallet: read its state, fetch its sealed key,
    hand over a transaction it signed itself, and read its history.

    Numerari never signs. The sealed key is opened on the agent's own machine with a signing secret that Numerari
    never sees. The relay only decodes a signed transaction, checks it against the wallet's policy, and broadcasts it.

    Every credential in the examples is a placeholder. Never paste a real key into a page, a ticket or a chat.
  contact:
    email: support@numerari.io
servers:
  - url: https://api.numerari.io
    description: Production
security:
  - accessKey: []
tags:
  - name: Wallet
  - name: Transactions
paths:
  /api/agent/v1/wallet:
    get:
      tags: [Wallet]
      operationId: getWallet
      summary: Get the wallet
      description: Address, status, spending policy, holder and supported chains. Readable while the wallet is paused.
      responses:
        '200':
          description: The wallet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Wallet'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/agent/v1/wallet/sealed-key:
    get:
      tags: [Wallet]
      operationId: getSealedKey
      summary: Get the sealed key
      description: |
        The sealed key as an opaque blob. The agent opens it locally with the signing secret. Available only while the
        wallet is neither paused nor revoked. The response is marked `Cache-Control: no-store`, and each fetch is
        recorded in the wallet's event log.
      responses:
        '200':
          description: The sealed key.
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SealedKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/agent/v1/transactions/relay:
    post:
      tags: [Transactions]
      operationId: relayTransaction
      summary: Relay a signed transaction
      description: |
        The agent signs a transaction itself and hands over the raw bytes. Numerari decodes it (it never signs), checks
        it, and broadcasts it. The body is limited to 64 KB.

        Before broadcasting, the relay checks that:

        - `chain_id` is a supported chain and matches the chain the transaction was signed for.
        - The transaction was signed by this wallet's own key.
        - It is a plain two-argument token call on a supported token contract, or a plain native-currency call with no
          data. Approvals, other contract calls and contract creation are refused.
        - The recipient is on the allow-list, if the owner set one.
        - The amount is within the per-transaction limit and the rolling 24-hour limit, if the owner set them.
        - Native-currency calls are refused while any amount limit is set (`unsupported_asset`), because a native amount
          has no USD value we can trust.
        - Native-currency calls with no amount limits are allowed only when the owner has set a recipient allow-list.
          Without one they are refused with `recipient_not_allowed`.

        Submitting the same signed bytes again never broadcasts a second transaction. If the earlier attempt was
        broadcast or confirmed, it returns that outcome. If it is still being relayed, it returns `relay_in_progress`.
        If the earlier outcome was unknown, the relay re-broadcasts the identical bytes, which is safe on chain. A
        resubmission is checked again like any other request, so a pause or a tighter limit since the first attempt
        gives that refusal instead of the earlier outcome. If a node refuses a resubmission you get
        `broadcast_unconfirmed` rather than `broadcast_failed`, because the earlier attempt may already be on the
        network. On `broadcast_unconfirmed`, resend the identical signed bytes (do not sign a new transaction) to learn
        the result.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RelayRequest'
            example:
              chain_id: 8453
              raw_tx: '0x02f8...'
      responses:
        '200':
          description: The transaction was accepted and its outcome is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelayResult'
              example:
                tx_hash: '0x...'
                chain_id: 8453
                status: broadcast
                to: '0x0000000000000000000000000000000000000000'
                token_symbol: USDC
                amount_units: '12.500000'
        '400':
          description: '`invalid_request` (the body must be JSON with `chain_id` and `raw_tx`) or `invalid_transaction` (`raw_tx` is not valid hex or not a supported signed transaction).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: '`relay_in_progress`: the same transaction is already being relayed.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: |
            The transaction was refused. `code` is one of `chain_not_supported`, `chain_mismatch`, `from_mismatch`,
            `unsupported_transaction`, `unsupported_asset`, `recipient_not_allowed`, `per_tx_limit_exceeded` or
            `daily_limit_exceeded`. A policy refusal never creates a history row.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: the amount exceeds this wallet's per-transaction limit
                code: per_tx_limit_exceeded
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          description: |
            `broadcast_failed`: the network node answered and rejected a first submission. `broadcast_unconfirmed`: the
            outcome is unknown (including when the node could not be reached). Resend the identical signed bytes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/agent/v1/transactions:
    get:
      tags: [Transactions]
      operationId: listTransactions
      summary: List relayed transactions
      description: History of transactions relayed for this wallet, newest first.
      parameters:
        - name: limit
          in: query
          description: Page size. Default 100, at most 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
        - name: offset
          in: query
          description: Number of rows to skip.
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: One page of history.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  securitySchemes:
    accessKey:
      type: http
      scheme: bearer
      description: |
        The access key, `nmr_ak_<id>_<secret>`. It identifies the wallet and lets the agent call the API. Numerari
        stores only a one-way hash of it, and the owner can replace it by rotating it. It stops working when the wallet
        is revoked or the team member holding the wallet is deactivated. Example (placeholder):
        `nmr_ak_EXAMPLEID1_example-secret-do-not-use`.
  responses:
    Unauthorized:
      description: |
        `invalid_access_key` (the key is malformed, unknown or wrong), `access_key_revoked` (the owner revoked or
        rotated this key) or `holder_disabled` (the team member holding this wallet was deactivated).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: access key is invalid
            code: invalid_access_key
    Forbidden:
      description: |
        `wallet_paused` (the owner paused the wallet; reads still work, the sealed key and relay do not),
        `wallet_revoked`, or `merchant_disabled` (the merchant account that owns this wallet was disabled; reads and
        relays are both refused).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: |
        `internal_error`: something went wrong on our side. If you were relaying a transaction, resend the exact same signed
        transaction (the identical bytes) and do not sign a new one: the first attempt may already be on the network, and
        a new signature would be a second payment. If it persists, contact support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal error
            code: internal_error
    RateLimited:
      description: |
        `rate_limited`. Wait for the `Retry-After` header, in seconds. If you were relaying a transaction, retry with the
        exact same signed transaction; do not sign a new one. Limits: 120 requests per minute per client
        address; 20 failed authentications per 5 minutes per client address; 60 read requests per minute per key; 10
        relay requests per minute per key. Counters are kept in memory on each server process, so treat them as
        approximate ceilings.
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required: [error, code]
      properties:
        error:
          type: string
          description: A human-readable message.
        code:
          type: string
          description: A stable code to branch on.
          enum:
            - invalid_access_key
            - access_key_revoked
            - holder_disabled
            - wallet_paused
            - wallet_revoked
            - merchant_disabled
            - invalid_request
            - invalid_transaction
            - relay_in_progress
            - chain_not_supported
            - chain_mismatch
            - from_mismatch
            - unsupported_transaction
            - unsupported_asset
            - recipient_not_allowed
            - per_tx_limit_exceeded
            - daily_limit_exceeded
            - rate_limited
            - broadcast_failed
            - broadcast_unconfirmed
            - internal_error
    Wallet:
      type: object
      required: [sub_wallet_id, bot_name, address, status, paused_at, holder, policy, chains]
      properties:
        sub_wallet_id:
          type: string
          format: uuid
        bot_name:
          type: string
        address:
          type: string
          description: The wallet's address.
        status:
          type: string
          enum: [active, paused, revoked]
        paused_at:
          type: [string, 'null']
        holder:
          type: object
          required: [type, label]
          properties:
            type:
              type: string
              examples: [agent]
            label:
              type: string
        policy:
          $ref: '#/components/schemas/Policy'
        chains:
          type: array
          description: The chains and tokens the relay accepts.
          items:
            $ref: '#/components/schemas/Chain'
      example:
        sub_wallet_id: 00000000-0000-0000-0000-000000000000
        bot_name: example-agent
        address: '0x0000000000000000000000000000000000000000'
        status: active
        paused_at: null
        holder:
          type: agent
          label: example-agent
        policy:
          max_per_tx_units: '50.000000'
          max_per_day_units: '200.000000'
          allowed_recipients: []
        chains:
          - chain_id: 1
            name: Ethereum Mainnet
            native_symbol: ETH
            tokens:
              - symbol: USDT
                contract_address: '0x...'
                decimals: 6
    Policy:
      type: object
      required: [max_per_tx_units, max_per_day_units, allowed_recipients]
      properties:
        max_per_tx_units:
          type: [string, 'null']
          description: Per-transaction limit as a decimal string in USD-stablecoin units with six decimal places. `null` means no limit.
        max_per_day_units:
          type: [string, 'null']
          description: Rolling 24-hour limit, same format. `null` means no limit.
        allowed_recipients:
          type: array
          description: An empty list means any recipient.
          items:
            type: string
    Chain:
      type: object
      required: [chain_id, name, native_symbol, tokens]
      properties:
        chain_id:
          type: integer
          format: int64
        name:
          type: string
        native_symbol:
          type: string
        tokens:
          type: array
          items:
            type: object
            required: [symbol, contract_address, decimals]
            properties:
              symbol:
                type: string
              contract_address:
                type: string
              decimals:
                type: integer
    SealedKey:
      type: object
      required: [sealed_key, blob_version]
      properties:
        sealed_key:
          type: string
          description: An opaque base64 blob. Open it locally with the signing secret.
        blob_version:
          type: integer
      example:
        sealed_key: <opaque base64 blob>
        blob_version: 1
    RelayRequest:
      type: object
      required: [chain_id, raw_tx]
      properties:
        chain_id:
          type: integer
          format: int64
          description: A supported chain. It must match the chain the transaction was signed for.
        raw_tx:
          type: string
          description: The signed transaction as hex, with the `0x` prefix.
    RelayResult:
      type: object
      required: [tx_hash, chain_id, status, to, token_symbol, amount_units]
      properties:
        tx_hash:
          type: string
        chain_id:
          type: integer
          format: int64
        status:
          $ref: '#/components/schemas/TransactionStatus'
        to:
          type: string
        token_symbol:
          type: [string, 'null']
        amount_units:
          type: string
          description: |
            Decimal string with six decimal places, in USD-stablecoin units. For a native-currency transfer it is
            `0.000000`, because a native amount is not counted in these units.
    TransactionStatus:
      type: string
      description: |
        A relayed transaction's status is one of five values. Branch on all of them.

        - `pending`: accepted and recorded, not yet broadcast.
        - `broadcast`: handed to the network, not yet seen mined.
        - `unknown`: the outcome is not known; the transaction may or may not be on the network. `failure_code` says why:
          `broadcast_unconfirmed`, `node_hash_mismatch` or `receipt_timeout`. Resend the identical signed bytes to learn
          the result. It counts toward the daily limit for 24 hours from the time it was reserved, after which it no
          longer does.
        - `confirmed`: mined successfully. Set later by Numerari's reconciler, so a transaction can read `broadcast` for
          a while first.
        - `failed`: the node rejected the transaction (`failure_code` `broadcast_failed`), or it was mined and reverted
          (`failure_code` `reverted`). A failed transaction frees its daily-limit slot.
      enum: [pending, broadcast, unknown, confirmed, failed]
    Transaction:
      type: object
      required: [id, chain_id, tx_hash, from, to, token_symbol, token_address, amount_units, status, failure_code, created_at, confirmed_at, block_number]
      properties:
        id:
          type: string
          format: uuid
        chain_id:
          type: integer
          format: int64
        tx_hash:
          type: string
        from:
          type: string
        to:
          type: string
        token_symbol:
          type: [string, 'null']
        token_address:
          type: [string, 'null']
        amount_units:
          type: string
          description: |
            Decimal string with six decimal places, in USD-stablecoin units. For a native-currency transfer it is
            `0.000000`, because a native amount is not counted in these units.
        status:
          $ref: '#/components/schemas/TransactionStatus'
        failure_code:
          type: [string, 'null']
        created_at:
          type: string
          format: date-time
        confirmed_at:
          type: [string, 'null']
          description: Null until the transaction is mined.
        block_number:
          type: [integer, 'null']
          description: Null until the transaction is mined.
    TransactionList:
      type: object
      required: [transactions, total, limit, offset]
      properties:
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        total:
          type: integer
          format: int64
        limit:
          type: integer
        offset:
          type: integer
