Ava API

openapi: 3.1.0
info:
  title: Ava API
  version: '2026-11-09'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-09: 18 operation(s) read from 6 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Ava has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 3
    documentation: 15
    pages-with-code: 4
    pages-read: 6
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-09'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://getava.xyz/docs
  - https://getava.xyz/dashboard
  - https://getava.xyz/receipts
  - https://getava.xyz/faq
  - https://getava.xyz/llms.txt
  - https://getava.xyz/verify/exec_lend_aave_62d2a6763c984af8be707a58
servers:
- url: https://ava-v4-api.fly.dev
paths:
  /:
    post:
      operationId: post
      tags:
      - Api
      summary: POST /
      x-source: https://getava.xyz/verify/exec_lend_aave_62d2a6763c984af8be707a58
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -s -X POST https://rpc.monad.xyz  -H ''content-type: application/json''  -d ''{"jsonrpc":"2.0","id":1,"method":"eth_getTransactionReceipt","params":["0x1b23c35d5c7c58746961777fdc9eb468823be549a3784869ff0d71b326628af7"]}''
          What the response must contain for this receipt to hold "status" "0x1" (the transaction succeeded) "to" 0x69a5f9ad4f96ebf0a0c792dd42a01cc5c0102fef
          "from" 0x648530a71280b27558b4f'
  /health:
    get:
      operationId: get_health
      tags:
      - Health
      summary: Liveness, degraded flag and dependency modes.
      x-source: https://getava.xyz/docs
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /matrix.json:
    get:
      operationId: get_matrix_json
      tags:
      - Matrix
      summary: GET /matrix.json
      x-source: https://getava.xyz/faq
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl is not a person. How are Ava receipts verified on chain? A receipt is not the executor''s own report of success. GET /v1/receipts/:ref/verify
          re-reads the settlement from a public RPC and states what it can prove: broadcast, inclusion, and whether the effect survived. A transaction
          hash proves broadcast and an included block proves inclusion, and neither proves the user asked for it. The recei'
  /v1/agents/{agentinstanceid}/record:
    get:
      operationId: get_v1_agents_agentinstanceid_record
      tags:
      - Agents
      summary: The agent's track record. Owner‑only unless the owner opted it public.
      x-source: https://getava.xyz/docs
      parameters:
      - name: agentinstanceid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1AgentsAgentinstanceidRecordResponse'
      x-evidence:
        kind: documentation
  /v1/agents/{agentinstanceid}/record/visibility:
    post:
      operationId: post_v1_agents_agentinstanceid_record_visibility
      tags:
      - Agents
      summary: Sets the record visibility.
      x-source: https://getava.xyz/docs
      parameters:
      - name: agentinstanceid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1AgentsAgentinstanceidRecordVisibilityRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/capabilities:
    get:
      operationId: get_v1_capabilities
      tags:
      - Capabilities
      summary: Adapters, brokers, wallet providers and their current mode.
      x-source: https://getava.xyz/docs
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/lend/execute:
    post:
      operationId: post_v1_lend_execute
      tags:
      - Lend
      summary: ava_lend_execute Execute a REAL lend against one of your mandates.
      x-source: https://getava.xyz/docs
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/mandates:
    get:
      operationId: get_v1_mandates
      tags:
      - Mandates
      summary: Lists your mandates, filterable by portal, agent instance and status.
      x-source: https://getava.xyz/docs
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_v1_mandates
      tags:
      - Mandates
      summary: Creates a mandate from structured fields or from a natural‑language message.
      x-source: https://getava.xyz/docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1MandatesRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1MandatesResponse'
      x-evidence:
        kind: documentation
  /v1/mandates/{id}/evaluate:
    post:
      operationId: post_v1_mandates_id_evaluate
      tags:
      - Mandates
      summary: Tests the mandate's conditions. Omit the snapshot and Ava pulls a live price for the condition asset.
      x-source: https://getava.xyz/docs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1MandatesIdEvaluateResponse'
      x-evidence:
        kind: documentation
  /v1/portal/catalog:
    get:
      operationId: get_v1_portal_catalog
      tags:
      - Portal
      summary: Portals, their chains and their wallet families.
      x-source: https://getava.xyz/docs
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/portfolio:
    get:
      operationId: get_v1_portfolio
      tags:
      - Portfolio
      summary: Simulated testnet portfolio for a userId (same data as GET /v1/portfolio).
      x-source: https://getava.xyz/docs
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/receipts/{ref}/verify:
    get:
      operationId: get_v1_receipts_ref_verify
      tags:
      - Receipts
      summary: How are Ava receipts verified on chain?
      x-source: https://getava.xyz/faq
      parameters:
      - name: ref
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/receipts/exec_lend_aave_62d2a6763c984af8be707a58:
    get:
      operationId: get_v1_receipts_exec_lend_aave_62d2a6763c984af8be707a58
      tags:
      - Receipts
      summary: Get a receipt you can check
      x-source: https://getava.xyz/receipts
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ReceiptsExecLendAave62D2A6763C984Af8Be707A58Response'
      x-evidence:
        kind: documentation
  /v1/users/me/agents:
    post:
      operationId: post_v1_users_me_agents
      tags:
      - Users
      summary: Registers an agent instance.
      x-source: https://getava.xyz/docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1UsersMeAgentsRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/users/me/wallets/provision:
    post:
      operationId: post_v1_users_me_wallets_provision
      tags:
      - Users
      summary: Provisions a custodial agent wallet in its own Turnkey sub‑organisation.
      x-source: https://getava.xyz/docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1UsersMeWalletsProvisionRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/users/session:
    post:
      operationId: post_v1_users_session
      tags:
      - Users
      summary: POST /v1/users/session
      x-source: https://getava.xyz/docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1UsersSessionResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -sS -X POST https://ava-v4-api.fly.dev/v1/users/session  -H 'content-type: application/json'  -d '{}' captured 2026-07-29\
          \ response {\n \"ok\": true,\n \"user\": {\n \"userId\": \"usr_96a9bb92c52be687\",\n \"createdAt\": \"2026-07-29T12:26:17.051Z\"\n },\n\
          \ \"wallets\": [],\n \"agents\": [],\n \"token\": \"ava_st_<32 random bytes, base64url, shown once>\",\n \"tokenId\": \"stk_6f0a1c2d3e4b5a69\"\
          ,\n \"sessionKind\": \"created\",\n \"r"
  /v1/workflows/execute:
    post:
      operationId: post_v1_workflows_execute
      tags:
      - Workflows
      summary: Executes a workflow plan (used for swap legs such as 0x, uniswap_v3, etc.).
      x-source: https://getava.xyz/docs
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    PostRequest:
      type: object
      properties:
        jsonrpc:
          type: string
        id:
          type: integer
        method:
          type: string
        params:
          type: array
          items:
            type: string
    GetV1AgentsAgentinstanceidRecordResponse:
      type: object
      properties:
        ok:
          type: boolean
        record.recordVersion:
          type: string
        record.agentInstanceId:
          type: string
        record.visibility:
          type: string
        record.stats:
          type: object
        record.verification:
          type: object
        record.generatedAt:
          type: string
    PostV1AgentsAgentinstanceidRecordVisibilityRequest:
      type: object
      properties:
        visibility:
          type: string
          description: '"owner" | "public"'
      required:
      - visibility
    PostV1MandatesRequest:
      type: object
      properties:
        objective:
          type: string
          description: 'enum: earn, hold, trade, rebalance, protect'
        capital:
          type: object
          description: asset, amount (string), chain
        constraints:
          type: object
          description: maxNotionalUsd (number) and other optional numeric fields
      required:
      - objective
      - capital
    PostV1MandatesResponse:
      type: object
      properties:
        ok:
          type: boolean
        mandate.mandateId:
          type: string
        mandate.userId:
          type: string
        mandate.portal:
          type: string
        mandate.name:
          type: string
        mandate.status:
          type: string
        mandate.objective:
          type: string
        mandate.capital:
          type: object
        mandate.constraints:
          type: object
        mandate.conditions:
          type: array
        mandate.action:
          type: object
        mandate.createdAt:
          type: string
        mandate.updatedAt:
          type: string
        nextStep:
          type: string
        requestId:
          type: string
    PostV1MandatesIdEvaluateResponse:
      type: object
      properties:
        matched:
          type: boolean
        evaluation.matched:
          type: boolean
        evaluation.reason:
          type: string
        evaluation.observed.price:
          type: number
        evaluation.observed.priceChangePct:
          type: number
        evaluation.observed.matchedIndexes:
          type: array
        evaluation.actionDispatched:
          type: boolean
        snapshot.price:
          type: number
        snapshot.priceChangePct:
          type: number
        snapshot.priceChangePct1h:
          type: number
        snapshot.source:
          type: string
        snapshot.asset:
          type: string
        snapshot.observedAt:
          type: string
    GetV1ReceiptsExecLendAave62D2A6763C984Af8Be707A58Response:
      type: object
      properties:
        receiptVersion:
          type: string
          description: Version identifier, e.g., "ava.exec.v1"
        executionId:
          type: string
          description: The execution identifier matching the request
        venue:
          type: string
          description: The venue, e.g., "aave"
        status:
          type: string
          description: Execution status, e.g., "filled"
        txHash:
          type: string
          description: Transaction hash on the chain
        blockNumber:
          type: integer
          description: Block number where the transaction was included
        attestation:
          type: object
          description: Attestation of on‑chain confirmation
        attestation.confirmed:
          type: boolean
          description: Whether the transaction was confirmed
        attestation.chain:
          type: string
          description: Chain name, e.g., "monad"
        attestation.source:
          type: string
          description: Source of attestation, e.g., "public-rpc"
        proof:
          type: object
          description: Proof of standing
        proof.standing:
          type: string
          description: Proof standing, e.g., "chain-confirmed"
        settlement:
          type: object
          description: Settlement standing
        settlement.standing:
          type: string
          description: Settlement standing, e.g., "matched"
    PostV1UsersMeAgentsRequest:
      type: object
      properties:
        portalSlug:
          type: string
        agentId:
          type: string
        label:
          type: string
      required:
      - portalSlug
      - agentId
    PostV1UsersMeWalletsProvisionRequest:
      type: object
      properties:
        family:
          type: string
          description: '"evm" | "solana" | "sui"'
      required:
      - family
    PostV1UsersSessionResponse:
      type: object
      properties:
        ok:
          type: boolean
        user:
          type: object
          properties:
            userId:
              type: string
            createdAt:
              type: string
              format: date-time
        wallets:
          type: array
          items: {}
        agents:
          type: array
          items: {}
        token:
          type: string
        tokenId:
          type: string
        sessionKind:
          type: string
        requestId:
          type: string
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Agents
- name: Api
- name: Capabilities
- name: Health
- name: Lend
- name: Mandates
- name: Matrix
- name: Portal
- name: Portfolio
- name: Receipts
- name: Users
- name: Workflows