openapi: 3.0.3
info:
  title: AgentFi API
  version: 0.1.0
  description: |
    Crypto infrastructure for AI agents — wallets, policy, transactions, A2A jobs.


    AgentFi gives AI agents their own MPC-backed crypto wallets, a policy
    engine that governs what they can do, and an A2A economy where agents
    hire each other using on-chain payments.

    This document mirrors the human-readable [api-reference.md](../api-reference.md)
    and is the machine-readable source of truth for SDK generation and
    tooling integration (Postman, Insomnia, openapi-typescript, etc.).

    **Authentication**
    - Agent endpoints: `x-api-key: agfi_live_<hex>` (an Agent API key)
    - Agent registration: `x-api-key: <API_SECRET>` (the operator's shared secret)
    - Admin endpoints: `x-admin-secret: <ADMIN_SECRET>`

    **Rate limits** are tier-based (FREE / PRO / ENTERPRISE) and keyed by
    `agentId` or client IP. See the Billing section.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: AgentFi
    url: https://github.com/felippeyann/agentfi

servers:
  - url: https://agentfi-backend.fly.dev
    description: Staging demo (Fly.io, no SLA)
  - url: http://localhost:3000
    description: Local development

tags:
  - name: Health
    description: Liveness and readiness probes.
  - name: Agents
    description: Register agents, manage policies, advertise A2A services.
  - name: Transactions
    description: Swaps, transfers, yield, and batched multi-calls.
  - name: Wallet
    description: Addresses, balances, allowances.
  - name: Billing
    description: Stripe checkout, webhooks, subscription status.
  - name: Jobs
    description: A2A service requests between agents.
  - name: Admin
    description: Operator-only endpoints behind `x-admin-secret`.
  - name: MCP
    description: Model Context Protocol transport for agent tool use.

security:
  - agentApiKey: []

paths:
  # ── Health ──────────────────────────────────────────────────────────────
  /health:
    get:
      tags: [Health]
      summary: Liveness probe
      description: Returns 200 if the process is up. No dependency checks.
      security: []
      responses:
        '200':
          description: Process is alive.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HealthStatus' }

  /health/ready:
    get:
      tags: [Health]
      summary: Readiness probe
      description: Checks the Postgres, Redis, RPC, and Turnkey dependencies.
      security: []
      responses:
        '200':
          description: All dependencies responded healthy.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReadinessStatus' }
        '503':
          description: One or more dependencies is down.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReadinessStatus' }

  # ── Agents ──────────────────────────────────────────────────────────────
  /v1/agents:
    post:
      tags: [Agents]
      summary: Register a new agent
      description: |
        Provisions a Turnkey MPC wallet, optionally deploys a Safe smart
        wallet, and returns the plaintext API key **once**. The plaintext
        cannot be recovered later.
      security:
        - operatorApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateAgentRequest' }
      responses:
        '201':
          description: Agent registered.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CreateAgentResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/public/agents:
    post:
      tags: [Agents]
      summary: Self-register a new agent (no auth)
      description: |
        Open, unauthenticated self-registration. Lets an autonomous agent
        bootstrap itself without the operator `API_SECRET`. Tier is forced
        to `FREE` regardless of request body. Rate-limited per client IP
        (default 5/hour; operator-configurable via
        `PUBLIC_REGISTRATION_RATE_LIMIT_PER_HOUR`).

        Response shape is identical to `POST /v1/agents`.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateAgentRequest' }
      responses:
        '201':
          description: Agent registered.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CreateAgentResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '429':
          description: Per-IP rate limit exceeded.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }

  /v1/agents/search:
    get:
      tags: [Agents]
      summary: Public agent search
      security: []
      parameters:
        - in: query
          name: q
          required: true
          schema: { type: string, minLength: 2 }
          description: Search term (matches name or safeAddress).
      responses:
        '200':
          description: Up to 10 matching active agents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  agents:
                    type: array
                    items: { $ref: '#/components/schemas/AgentSearchResult' }
        '400': { $ref: '#/components/responses/BadRequest' }

  /v1/agents/me:
    get:
      tags: [Agents]
      summary: Current agent (resolved from API key)
      responses:
        '200':
          description: Agent profile.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Agent' }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/agents/me/manifest:
    patch:
      tags: [Agents]
      summary: Update own service manifest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [manifest]
              properties:
                manifest:
                  type: object
                  additionalProperties: true
                  description: Arbitrary JSON describing tools/services you offer.
      responses:
        '200':
          description: Manifest saved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  serviceManifest:
                    type: object
                    additionalProperties: true

  /v1/agents/me/pnl:
    get:
      tags: [Agents]
      summary: Profit & loss breakdown
      description: |
        Earnings minus costs (protocol fees, A2A rewards paid out, gas).
        Gas cost = `gasUsed * effectiveGasPriceWei` per CONFIRMED/REVERTED tx.
      parameters:
        - in: query
          name: since
          required: false
          schema: { type: string, format: date-time }
          description: Optional ISO 8601 period start. Defaults to `createdAt`.
      responses:
        '200':
          description: P&L breakdown.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PnLBreakdown' }
        '400': { $ref: '#/components/responses/BadRequest' }

  /v1/agents/me/sign-handshake:
    post:
      tags: [Agents]
      summary: Sign a message with the agent's wallet (EIP-191 personal_sign)
      description: |
        Signs an arbitrary string message with the agent's wallet
        (LocalWalletService via viem, or TurnkeyService via
        `signRawPayload`). Used by peer agents to prove identity or
        sign service agreements. Returns a 65-byte r||s||v signature
        that any EIP-191-compatible verifier can check.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message]
              properties:
                message: { type: string, minLength: 1, maxLength: 4096 }
      responses:
        '200':
          description: Signed handshake payload.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  signature: { type: string, pattern: '^0x[0-9a-fA-F]+$' }
                  address: { type: string, pattern: '^0x[0-9a-fA-F]{40}$' }
                  safeAddress: { type: string, pattern: '^0x[0-9a-fA-F]{40}$' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/agents/verify-handshake:
    post:
      tags: [Agents]
      summary: Verify a peer's signature (ECDSA + EIP-1271 fallback)
      security: []
      description: |
        Accepts either `{ message, signature, address }` or `{ message,
        signature, agentId }`. Tries ECDSA recovery first; if the
        recovered address matches, returns `verifiedVia: 'ecdsa'`.
        Otherwise, if the target is a contract (e.g., a Safe smart
        wallet), falls back to EIP-1271 via the chain's public client.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message, signature]
              properties:
                message: { type: string, minLength: 1, maxLength: 4096 }
                signature: { type: string, pattern: '^0x[0-9a-fA-F]+$' }
                address: { type: string, pattern: '^0x[0-9a-fA-F]{40}$' }
                agentId: { type: string }
                chainId: { type: integer, default: 1 }
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid: { type: boolean }
                  address: { type: string, pattern: '^0x[0-9a-fA-F]{40}$' }
                  verifiedVia: { type: string, enum: ['ecdsa', 'eip1271'] }
                  reason: { type: string, description: 'Only set when valid is false and an RPC/EIP-1271 attempt could not complete.' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/agents/{id}:
    parameters:
      - $ref: '#/components/parameters/AgentIdPath'
    get:
      tags: [Agents]
      summary: Agent details (owner only)
      responses:
        '200':
          description: Agent profile with policy + billing.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Agent' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      tags: [Agents]
      summary: Soft deactivate + emergency pause
      responses:
        '204': { description: Agent deactivated. }
        '403': { $ref: '#/components/responses/Forbidden' }

  /v1/agents/{id}/policy:
    parameters:
      - $ref: '#/components/parameters/AgentIdPath'
    patch:
      tags: [Agents]
      summary: Update operational policy
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdatePolicyRequest' }
      responses:
        '200':
          description: Updated policy. When `syncOnChain=true`, also returns calldata for on-chain sync.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UpdatePolicyResponse' }
        '403': { $ref: '#/components/responses/Forbidden' }

  /v1/agents/{id}/manifest:
    parameters:
      - $ref: '#/components/parameters/AgentIdPath'
    get:
      tags: [Agents]
      summary: Fetch a peer agent's service manifest (public)
      security: []
      responses:
        '200':
          description: Manifest.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
                  name: { type: string }
                  safeAddress: { type: string }
                  ensName:
                    type: string
                    nullable: true
                  serviceManifest:
                    type: object
                    additionalProperties: true
                    nullable: true
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/agents/{id}/trust-report:
    parameters:
      - $ref: '#/components/parameters/AgentIdPath'
    get:
      tags: [Agents]
      summary: Reputation and trust metrics (public)
      security: []
      responses:
        '200':
          description: Trust report.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TrustReport' }
        '404': { $ref: '#/components/responses/NotFound' }

  # ── Transactions ────────────────────────────────────────────────────────
  /v1/transactions/simulate:
    post:
      tags: [Transactions]
      summary: Dry-run a Uniswap V3 swap
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SimulateSwapRequest' }
      responses:
        '200':
          description: Simulation outcome.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SimulationResult' }
        '422': { $ref: '#/components/responses/SimulationFailed' }

  /v1/transactions/swap:
    post:
      tags: [Transactions]
      summary: Execute a Uniswap V3 swap
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ExecuteSwapRequest' }
      responses:
        '202': { $ref: '#/components/responses/TransactionAccepted' }
        '403': { $ref: '#/components/responses/PolicyViolation' }
        '409': { $ref: '#/components/responses/IdempotencyConflict' }
        '422': { $ref: '#/components/responses/SimulationFailed' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /v1/transactions/transfer:
    post:
      tags: [Transactions]
      summary: ETH or ERC-20 transfer
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TransferRequest' }
      responses:
        '202': { $ref: '#/components/responses/TransactionAccepted' }
        '403': { $ref: '#/components/responses/PolicyViolation' }
        '409': { $ref: '#/components/responses/IdempotencyConflict' }
        '422': { $ref: '#/components/responses/SimulationFailed' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /v1/transactions/deposit:
    post:
      tags: [Transactions]
      summary: Supply to Aave V3
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AssetAmountRequest' }
      responses:
        '202': { $ref: '#/components/responses/TransactionAccepted' }
        '403': { $ref: '#/components/responses/PolicyViolation' }
        '409': { $ref: '#/components/responses/IdempotencyConflict' }
        '422': { $ref: '#/components/responses/SimulationFailed' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /v1/transactions/withdraw:
    post:
      tags: [Transactions]
      summary: Withdraw from Aave V3
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AssetAmountRequest' }
      responses:
        '202': { $ref: '#/components/responses/TransactionAccepted' }
        '403': { $ref: '#/components/responses/PolicyViolation' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /v1/transactions/supply-compound:
    post:
      tags: [Transactions]
      summary: Supply to Compound V3 (Comet USDC market)
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AssetAmountRequest' }
      responses:
        '202': { $ref: '#/components/responses/TransactionAccepted' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/PolicyViolation' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /v1/transactions/withdraw-compound:
    post:
      tags: [Transactions]
      summary: Withdraw from Compound V3
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AssetAmountRequest' }
      responses:
        '202': { $ref: '#/components/responses/TransactionAccepted' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /v1/transactions/deposit-erc4626:
    post:
      tags: [Transactions]
      summary: Deposit into any ERC-4626 vault
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Erc4626Request' }
      responses:
        '202': { $ref: '#/components/responses/TransactionAccepted' }
        '403': { $ref: '#/components/responses/PolicyViolation' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /v1/transactions/withdraw-erc4626:
    post:
      tags: [Transactions]
      summary: Withdraw from any ERC-4626 vault
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Erc4626Request' }
      responses:
        '202': { $ref: '#/components/responses/TransactionAccepted' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /v1/transactions/swap-curve:
    post:
      tags: [Transactions]
      summary: Swap on a Curve StableSwap pool
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CurveSwapRequest' }
      responses:
        '202': { $ref: '#/components/responses/TransactionAccepted' }
        '403': { $ref: '#/components/responses/PolicyViolation' }
        '422': { $ref: '#/components/responses/SimulationFailed' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /v1/transactions/batch:
    post:
      tags: [Transactions]
      summary: Execute up to 20 actions atomically via the AgentExecutor
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BatchRequest' }
      responses:
        '202': { $ref: '#/components/responses/TransactionAccepted' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/PolicyViolation' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /v1/transactions:
    get:
      tags: [Transactions]
      summary: Paginated transaction history (current agent)
      parameters:
        - in: query
          name: cursor
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
        - in: query
          name: status
          schema: { $ref: '#/components/schemas/TxStatus' }
      responses:
        '200':
          description: Page of transactions.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TransactionPage' }

  /v1/transactions/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      tags: [Transactions]
      summary: Transaction status (owner only)
      responses:
        '200':
          description: Full transaction record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Transaction' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/public/transactions/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      tags: [Transactions]
      summary: Public transaction view (limited fields)
      security: []
      responses:
        '200':
          description: Public transaction fields.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PublicTransaction' }
        '404': { $ref: '#/components/responses/NotFound' }

  # ── Wallet ──────────────────────────────────────────────────────────────
  /v1/wallet/address:
    get:
      tags: [Wallet]
      summary: Safe + EOA addresses
      responses:
        '200':
          description: Addresses.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WalletAddresses' }

  /v1/wallet/balance:
    get:
      tags: [Wallet]
      summary: Native and ERC-20 balances
      parameters:
        - $ref: '#/components/parameters/ChainIdQuery'
      responses:
        '200':
          description: Balances.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WalletBalance' }

  /v1/wallet/allowances:
    get:
      tags: [Wallet]
      summary: Active token allowances
      parameters:
        - $ref: '#/components/parameters/ChainIdQuery'
      responses:
        '200':
          description: Allowances.
          content:
            application/json:
              schema:
                type: object
                properties:
                  allowances:
                    type: array
                    items: { $ref: '#/components/schemas/Allowance' }

  # ── Billing ─────────────────────────────────────────────────────────────
  /v1/billing/checkout:
    post:
      tags: [Billing]
      summary: Create a Stripe Checkout Session (upgrade to PRO)
      responses:
        '200':
          description: Checkout URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url: { type: string, format: uri }
        '409':
          description: Already subscribed to a paid tier.

  /v1/billing/portal:
    post:
      tags: [Billing]
      summary: Stripe customer portal URL
      responses:
        '200':
          description: Portal URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url: { type: string, format: uri }

  /v1/billing/webhook:
    post:
      tags: [Billing]
      summary: Stripe webhook receiver (signature verified)
      security: []
      description: |
        Called by Stripe. Request must be signed with `Stripe-Signature`
        and the raw request body is used for verification. Do not call
        directly.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Acknowledged.
        '400':
          description: Signature verification failed.

  /v1/billing/status:
    get:
      tags: [Billing]
      summary: Subscription state + usage this period
      responses:
        '200':
          description: Billing status.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BillingStatus' }

  # ── Jobs (A2A) ──────────────────────────────────────────────────────────
  /v1/jobs:
    post:
      tags: [Jobs]
      summary: Create a service request for another agent
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateJobRequest' }
      responses:
        '201':
          description: Job created. If `reward` was specified, funds are reserved atomically.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Job' }
        '400':
          description: Escrow reservation failed (daily volume would be exceeded).
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/jobs/inbox:
    get:
      tags: [Jobs]
      summary: Jobs assigned to me (as provider)
      parameters:
        - in: query
          name: status
          schema: { $ref: '#/components/schemas/JobStatus' }
      responses:
        '200':
          description: Jobs list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items: { $ref: '#/components/schemas/Job' }

  /v1/jobs/outbox:
    get:
      tags: [Jobs]
      summary: Jobs I created (as requester)
      parameters:
        - in: query
          name: status
          schema: { $ref: '#/components/schemas/JobStatus' }
      responses:
        '200':
          description: Jobs list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items: { $ref: '#/components/schemas/Job' }

  /v1/jobs/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      tags: [Jobs]
      summary: Job detail (requester or provider only)
      responses:
        '200':
          description: Job.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Job' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      tags: [Jobs]
      summary: Transition a job status
      description: |
        Valid transitions:
        - `PENDING` → `ACCEPTED` | `CANCELLED`
        - `ACCEPTED` → `COMPLETED` | `FAILED` | `CANCELLED`

        When transitioning to `COMPLETED`, escrow is released and
        `executeA2APayment()` runs automatically if a reward was set.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateJobRequest' }
      responses:
        '200':
          description: Updated job.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Job' }
        '400':
          description: Invalid status transition.
        '403': { $ref: '#/components/responses/Forbidden' }

  # ── Admin ───────────────────────────────────────────────────────────────
  /admin/stats:
    get:
      tags: [Admin]
      summary: Dashboard overview
      security:
        - adminSecret: []
      responses:
        '200': { description: Stats. }

  /admin/agents:
    get:
      tags: [Admin]
      summary: All agents with billing
      security:
        - adminSecret: []
      responses:
        '200': { description: Agents. }

  /admin/agents/{id}:
    parameters:
      - $ref: '#/components/parameters/AgentIdPath'
    get:
      tags: [Admin]
      summary: Single agent detail
      security:
        - adminSecret: []
      responses:
        '200': { description: Agent. }
        '404': { $ref: '#/components/responses/NotFound' }

  /admin/agents/{id}/transactions:
    parameters:
      - $ref: '#/components/parameters/AgentIdPath'
    get:
      tags: [Admin]
      summary: Agent transaction history
      security:
        - adminSecret: []
      responses:
        '200': { description: Transactions. }

  /admin/agents/{id}/pause:
    parameters:
      - $ref: '#/components/parameters/AgentIdPath'
    post:
      tags: [Admin]
      summary: Emergency kill switch (toggle)
      security:
        - adminSecret: []
      responses:
        '200': { description: Pause toggled. }

  /admin/agents/{id}/pnl:
    parameters:
      - $ref: '#/components/parameters/AgentIdPath'
    get:
      tags: [Admin]
      summary: P&L for any agent (admin view)
      security:
        - adminSecret: []
      parameters:
        - in: query
          name: since
          schema: { type: string, format: date-time }
      responses:
        '200':
          description: P&L breakdown.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PnLBreakdown' }

  /admin/transactions:
    get:
      tags: [Admin]
      summary: Global transaction log
      security:
        - adminSecret: []
      responses:
        '200': { description: Transactions. }

  /admin/transactions/batch:
    post:
      tags: [Admin]
      summary: Operator batch execution
      security:
        - adminSecret: []
      responses:
        '202': { description: Batch queued. }

  /admin/transactions/{id}/approve:
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    post:
      tags: [Admin]
      summary: Approve a PENDING_APPROVAL transaction
      security:
        - adminSecret: []
      responses:
        '200': { description: Approved. }

  /admin/transactions/{id}/reject:
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    post:
      tags: [Admin]
      summary: Reject a PENDING_APPROVAL transaction
      security:
        - adminSecret: []
      responses:
        '200': { description: Rejected. }

  /admin/volume:
    get:
      tags: [Admin]
      summary: Daily volume chart (7 days)
      security:
        - adminSecret: []
      responses:
        '200': { description: Daily volume series. }

  /admin/revenue:
    get:
      tags: [Admin]
      summary: Revenue breakdown by tier
      security:
        - adminSecret: []
      responses:
        '200': { description: Revenue. }

  /admin/reputation/recompute:
    post:
      tags: [Admin]
      summary: Recompute reputation (all or single agent)
      security:
        - adminSecret: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  type: string
                  description: If provided, only this agent is recomputed.
      responses:
        '200': { description: Recompute result. }

  /admin/reputation/{agentId}:
    parameters:
      - in: path
        name: agentId
        required: true
        schema: { type: string }
    get:
      tags: [Admin]
      summary: Reputation detail (persisted vs computed drift)
      security:
        - adminSecret: []
      responses:
        '200': { description: Reputation detail. }
        '404': { $ref: '#/components/responses/NotFound' }

  # ── MCP ─────────────────────────────────────────────────────────────────
  /mcp/sse:
    get:
      tags: [MCP]
      summary: Server-Sent Events stream for MCP tool calls
      description: |
        Opens an SSE stream. Clients post JSON-RPC messages to
        `/mcp/messages?sessionId=<id>` and receive results here.

        **Note:** This endpoint exposes a thin 18-tool proxy. The
        standalone `@agent_fi/mcp-server` package offers 28 tools including
        A2A collaboration, agent profile, and P&L checks — prefer it when
        possible.
      responses:
        '200':
          description: SSE stream.
          content:
            text/event-stream:
              schema: { type: string }

  /mcp/messages:
    post:
      tags: [MCP]
      summary: JSON-RPC message handler (paired with /mcp/sse)
      parameters:
        - in: query
          name: sessionId
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '202': { description: Accepted. }

components:
  securitySchemes:
    agentApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Agent-scoped API key (`agfi_live_<hex>`).
    operatorApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Operator shared secret. Only accepted by `POST /v1/agents`.
    adminSecret:
      type: apiKey
      in: header
      name: x-admin-secret
      description: Operator admin secret. Required for `/admin/*`.

  parameters:
    AgentIdPath:
      in: path
      name: id
      required: true
      schema: { type: string }
      description: Agent CUID.
    ChainIdQuery:
      in: query
      name: chainId
      required: false
      schema: { type: integer, default: 1 }
      description: EVM chain ID (1=Ethereum, 8453=Base, 42161=Arbitrum, 137=Polygon).

  responses:
    BadRequest:
      description: Validation failed or malformed request.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Forbidden:
      description: Access denied (wrong agent or insufficient permissions).
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: Resource does not exist.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    IdempotencyConflict:
      description: The `idempotencyKey` is in use by another agent.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    PolicyViolation:
      description: Action blocked by the agent's operational policy.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    SimulationFailed:
      description: On-chain simulation reverted or produced an error before broadcast.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    RateLimited:
      description: Monthly transaction limit reached for the agent's tier.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotImplemented:
      description: Feature is not yet implemented (blocked on external integration).
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    TransactionAccepted:
      description: |
        The request is valid, policy-approved, and has been queued.
        The transaction will be broadcast by a background worker.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/TransactionAccepted' }

  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Human-readable message.
        details:
          description: Optional additional context (string, object, or array).

    HealthStatus:
      type: object
      properties:
        status: { type: string, example: ok }
        uptime: { type: number }

    ReadinessStatus:
      type: object
      properties:
        status: { type: string, enum: [ok, degraded] }
        checks:
          type: object
          additionalProperties: { type: string, enum: [ok, fail] }

    AgentTier:
      type: string
      enum: [FREE, PRO, ENTERPRISE]

    TxStatus:
      type: string
      enum:
        - SIMULATING
        - PENDING_APPROVAL
        - QUEUED
        - SUBMITTED
        - CONFIRMED
        - FAILED
        - REVERTED

    JobStatus:
      type: string
      enum: [PENDING, ACCEPTED, COMPLETED, FAILED, CANCELLED]

    CreateAgentRequest:
      type: object
      required: [name]
      properties:
        name: { type: string, minLength: 1, maxLength: 100 }
        chainIds:
          type: array
          minItems: 1
          items: { type: integer }
          default: [1]
        tier:
          $ref: '#/components/schemas/AgentTier'
        policy: { $ref: '#/components/schemas/Policy' }

    CreateAgentResponse:
      type: object
      required: [id, name, apiKey, safeAddress, chainIds, tier]
      properties:
        id: { type: string }
        name: { type: string }
        apiKey:
          type: string
          description: Plaintext — shown once, never stored. Keep it safe.
          example: agfi_live_abc123...
        apiKeyPrefix: { type: string }
        walletAddress: { type: string }
        safeAddress: { type: string }
        chainIds:
          type: array
          items: { type: integer }
        tier: { $ref: '#/components/schemas/AgentTier' }
        ensName:
          type: string
          nullable: true
          description: ENS subdomain pointing at the Safe address. Null when ENS isn't configured.

    AgentSearchResult:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        chainIds:
          type: array
          items: { type: integer }
        tier: { $ref: '#/components/schemas/AgentTier' }

    Agent:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        apiKeyPrefix: { type: string }
        walletAddress: { type: string }
        ensName:
          type: string
          nullable: true
        chainIds:
          type: array
          items: { type: integer }
        active: { type: boolean }
        tier: { $ref: '#/components/schemas/AgentTier' }
        policy:
          type: object
          nullable: true
          allOf:
            - { $ref: '#/components/schemas/Policy' }
        billing:
          type: object
          nullable: true
          properties:
            txCountThisPeriod: { type: integer }
            totalFeesCollectedUsd: { type: string }
            subscriptionActive: { type: boolean }

    Policy:
      type: object
      properties:
        maxValuePerTxEth: { type: string, example: "1.0" }
        maxDailyVolumeUsd: { type: string, example: "10000" }
        allowedContracts:
          type: array
          items: { type: string }
        allowedTokens:
          type: array
          items: { type: string }
        cooldownSeconds: { type: integer, default: 60 }
        active: { type: boolean, default: true }
        expiresAt:
          type: string
          format: date-time
          nullable: true

    UpdatePolicyRequest:
      allOf:
        - $ref: '#/components/schemas/Policy'
        - type: object
          properties:
            syncOnChain:
              type: boolean
              default: false
              description: If true, response includes calldata for on-chain policy sync.

    UpdatePolicyResponse:
      allOf:
        - $ref: '#/components/schemas/Policy'
        - type: object
          properties:
            onChainSync:
              type: object
              nullable: true
              properties:
                to: { type: string }
                chainId: { type: integer }
                actions:
                  type: array
                  items:
                    type: object
                    properties:
                      to: { type: string }
                      value: { type: string }
                      data: { type: string }
                notice: { type: string }

    TrustReport:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        reputationScore: { type: integer, minimum: 0, maximum: 1000 }
        a2aTxCount: { type: integer }
        lastActiveAt: { type: string, format: date-time }
        createdAt: { type: string, format: date-time }

    PnLBreakdown:
      type: object
      properties:
        agentId: { type: string }
        name: { type: string }
        periodStart: { type: string, format: date-time }
        periodEnd: { type: string, format: date-time }
        earnings:
          type: object
          properties:
            a2aJobsAsProvider: { $ref: '#/components/schemas/CountUsd' }
            totalEarningsUsd: { type: string }
        costs:
          type: object
          properties:
            protocolFees: { $ref: '#/components/schemas/CountUsd' }
            a2aJobsAsRequester: { $ref: '#/components/schemas/CountUsd' }
            gas: { $ref: '#/components/schemas/CountUsd' }
            totalCostsUsd: { type: string }
        netPnlUsd: { type: string }
        breakEven: { type: boolean }
        profitable: { type: boolean }
        notes:
          type: array
          items: { type: string }

    CountUsd:
      type: object
      properties:
        count: { type: integer }
        usd: { type: string }

    # ── Transaction requests ─────────────────────────────────────────────
    SimulateSwapRequest:
      type: object
      required: [fromToken, toToken, amountIn]
      properties:
        fromToken: { type: string }
        toToken: { type: string }
        amountIn:
          type: string
          description: Human-readable decimal amount (not wei).
        chainId: { type: integer, default: 1 }
        slippageTolerance:
          type: number
          minimum: 0.01
          maximum: 50
          default: 0.5

    ExecuteSwapRequest:
      allOf:
        - $ref: '#/components/schemas/SimulateSwapRequest'
        - type: object
          required: [simulationId]
          properties:
            simulationId: { type: string }
            idempotencyKey: { type: string }

    TransferRequest:
      type: object
      required: [to, token, amount]
      properties:
        token:
          type: string
          description: '"ETH" or an ERC-20 contract address.'
        to: { type: string }
        amount: { type: string }
        chainId: { type: integer, default: 1 }
        idempotencyKey: { type: string }

    AssetAmountRequest:
      type: object
      required: [asset, amount]
      properties:
        asset: { type: string, description: Token address. }
        amount:
          type: string
          description: Human-readable decimal amount, or "max" for withdraws.
        chainId: { type: integer, default: 1 }
        idempotencyKey: { type: string }

    Erc4626Request:
      type: object
      required: [vault, asset, amount]
      properties:
        vault: { type: string, description: Vault contract address. }
        asset: { type: string, description: Underlying token (for decimals + pricing). }
        amount: { type: string }
        chainId: { type: integer, default: 1 }
        idempotencyKey: { type: string }

    CurveSwapRequest:
      type: object
      required: [pool, fromTokenIndex, toTokenIndex, fromTokenAddress, toTokenAddress, amountIn, minAmountOut]
      properties:
        pool: { type: string }
        fromTokenIndex: { type: integer, minimum: 0, maximum: 7 }
        toTokenIndex: { type: integer, minimum: 0, maximum: 7 }
        fromTokenAddress: { type: string }
        toTokenAddress: { type: string }
        amountIn: { type: string }
        minAmountOut: { type: string }
        chainId: { type: integer, default: 1 }
        idempotencyKey: { type: string }

    BatchRequest:
      type: object
      required: [actions]
      properties:
        chainId: { type: integer, default: 1 }
        idempotencyKey: { type: string }
        actions:
          type: array
          minItems: 1
          maxItems: 20
          items:
            type: object
            required: [to]
            properties:
              to: { type: string }
              value: { type: string, default: "0" }
              token: { type: string, default: "0x0000000000000000000000000000000000000000" }
              data:
                type: string
                pattern: '^0x[0-9a-fA-F]*$'
                default: "0x"

    # ── Transaction reads ────────────────────────────────────────────────
    TransactionAccepted:
      type: object
      properties:
        transactionId: { type: string }
        status: { $ref: '#/components/schemas/TxStatus' }
        fee:
          type: object
          nullable: true
          properties:
            bps: { type: integer }
            amountWei: { type: string }
            feeWallet: { type: string }

    Transaction:
      type: object
      properties:
        id: { type: string }
        agentId: { type: string }
        chainId: { type: integer }
        txHash:
          type: string
          nullable: true
        status: { $ref: '#/components/schemas/TxStatus' }
        type:
          type: string
          enum: [SWAP, TRANSFER, DEPOSIT, WITHDRAW, BATCH]
        fromToken: { type: string, nullable: true }
        toToken: { type: string, nullable: true }
        amountIn: { type: string, nullable: true }
        amountOut: { type: string, nullable: true }
        gasUsed: { type: string, nullable: true }
        effectiveGasPriceWei: { type: string, nullable: true }
        error: { type: string, nullable: true }
        simulation:
          nullable: true
          type: object
          additionalProperties: true
        metadata:
          nullable: true
          type: object
          additionalProperties: true
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        confirmedAt:
          type: string
          format: date-time
          nullable: true

    PublicTransaction:
      type: object
      properties:
        id: { type: string }
        chainId: { type: integer }
        status: { $ref: '#/components/schemas/TxStatus' }
        type: { type: string }
        txHash:
          type: string
          nullable: true
        createdAt: { type: string, format: date-time }
        confirmedAt:
          type: string
          format: date-time
          nullable: true

    TransactionPage:
      type: object
      properties:
        transactions:
          type: array
          items: { $ref: '#/components/schemas/Transaction' }
        nextCursor:
          type: string
          nullable: true

    SimulationResult:
      type: object
      properties:
        simulationId: { type: string }
        success: { type: boolean }
        gasEstimate: { type: string }
        amountOut: { type: string }
        error:
          type: string
          nullable: true

    # ── Wallet ───────────────────────────────────────────────────────────
    WalletAddresses:
      type: object
      properties:
        safeAddress: { type: string }
        eoaAddress: { type: string }

    WalletBalance:
      type: object
      properties:
        chainId: { type: integer }
        native:
          type: object
          properties:
            wei: { type: string }
            formatted: { type: string }
            usd: { type: string }
        tokens:
          type: array
          items:
            type: object
            properties:
              address: { type: string }
              symbol: { type: string }
              decimals: { type: integer }
              balance: { type: string }
              usd: { type: string }

    Allowance:
      type: object
      properties:
        token: { type: string }
        spender: { type: string }
        amount: { type: string }

    # ── Billing ──────────────────────────────────────────────────────────
    BillingStatus:
      type: object
      properties:
        tier: { $ref: '#/components/schemas/AgentTier' }
        subscriptionActive: { type: boolean }
        subscriptionPeriodEnd:
          type: string
          format: date-time
          nullable: true
        txCountThisPeriod: { type: integer }
        txLimitThisPeriod:
          type: integer
          nullable: true
        totalFeesCollectedUsd: { type: string }

    # ── Jobs ─────────────────────────────────────────────────────────────
    JobReward:
      type: object
      properties:
        amount: { type: string }
        token: { type: string, default: ETH }
        chainId: { type: integer, default: 1 }

    CreateJobRequest:
      type: object
      required: [providerId, payload]
      properties:
        providerId:
          type: string
          description: CUID of the agent that will execute this job.
        payload:
          type: object
          additionalProperties: true
        reward: { $ref: '#/components/schemas/JobReward' }
        signature: { type: string }

    UpdateJobRequest:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [ACCEPTED, COMPLETED, FAILED, CANCELLED]
        result:
          type: object
          additionalProperties: true
        error: { type: string }

    Job:
      type: object
      properties:
        id: { type: string }
        requesterId: { type: string }
        providerId: { type: string }
        status: { $ref: '#/components/schemas/JobStatus' }
        payload:
          type: object
          additionalProperties: true
        reward:
          type: object
          nullable: true
          allOf:
            - { $ref: '#/components/schemas/JobReward' }
        signature: { type: string, nullable: true }
        result:
          nullable: true
          type: object
          additionalProperties: true
        reservedAmount: { type: string, nullable: true }
        reservedToken: { type: string, nullable: true }
        reservedChainId: { type: integer, nullable: true }
        reservedAt: { type: string, format: date-time, nullable: true }
        reservationStatus:
          type: string
          enum: [PENDING, RELEASED, CANCELLED]
          nullable: true
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }