FarmDash Agent Hub Intelligence API

openapi: 3.2.0
info:
  title: FarmDash Agent Intelligence API
  version: 2.0.0
  description: 'WARNING: Running trade executions and cancellations places real perpetual futures trades and alters active market exposure, carrying significant risk of financial loss. Immediate, explicit manual end-user confirmation and consent is strictly required immediately before placing any execution or cancellation request. Do not allow autonomous agents to auto-run trade execution or cancellation without manual user approval. FarmDash is an intelligence and control layer for DeFi agents and serious airdrop farmers. This API covers swap transaction preparation (Signal Architect),

    protocol discovery intelligence (Trail Heat), perpetual futures (Futures Strategist), portfolio

    research, bounded autonomous sessions, x402 payment flows, and agent-readable opportunity intelligence. FarmDash does not request seed phrases or raw wallet private keys. Compatibility

    swap routes do not custody funds; separately configured venue or MPC delegations

    remain subject to their provider controls and explicit policy bounds. ## Authentication & Credential Lifecycle

    | Tier | Price | Auth | Rate Limit | Key Prefix | Entitlements | Best for |

    |------|-------|------|------------|------------|--------------|----------|

    | Scout | Free | None | 30 req / 24 h per IP | `fd_scout_free` | Keyless public discovery and quotes | Keyless discovery and quotes |

    | Pioneer | $39.99/mo USDC | `Authorization: Bearer ` | 1,500 req / day | `fd_pio_` | Premium research, full Trail Heat, wallet analytics, sybil audits | Serious farmers, full datasets, sybil audits, wallet analytics |

    | Syndicate | $199/mo USDC | `Authorization: Bearer ` | 50,000 req / day | `fd_syn_` | All Pioneer features plus advanced control tooling, bounded autopilot, webhooks, unrestricted CORS | Teams, serious agents, high-volume API use, webhooks, unrestricted CORS, advanced control/session tooling |


    ### Paid Entitlement & Key Issuance Sequence:

    1. **Pay**: Transfer USDC ($39.99/mo for Pioneer, $199/mo for Syndicate) on Base, Arbitrum, Optimism, Polygon, Ethereum, or Linea to the FarmDash treasury. 2. **Verify**: Post transaction hash and wallet to `verify-payment` to record on-chain confirmation in `users` and `payment_events`. 3. **Sign Proof**: Sign an EIP-712 `ApiKeyRequest` with the paying wallet (domain: `FarmDash`, intent: `Issue FarmDash API key`, single-use `nonce`). 4. **Receive Credential**: Post the signed payload to `/api/v1/agent/api-key`. The credential tier is server-authoritative, derived exclusively from your active paid subscription (client input cannot downgrade or elevate your tier). The plaintext key is returned exactly once; FarmDash stores only a SHA-256 hash. 5. **Authenticate**: Send `Authorization: Bearer ` on all requests. Daily limits reset every 24 hours (`X-RateLimit-Remaining`). Keys expire with your 30-day subscription; expired keys return HTTP 402 Payment Required. Higher-tier Syndicate capabilities (`advanced_control`) remain blocked for Pioneer subscribers. For SDK development without live data, use the deterministic sandbox on

    the two endpoints that explicitly support it (`/v1/agent/protocols` and

    `/v1/trail-heat`):

    `?mock=true`, `X-FarmDash-Mock: true`, or `Authorization: Bearer fd_sandbox_mock`

    Quote mock requests return typed `mock_not_supported` without contacting a live provider. Swap execution requires a fresh successful preflight simulation plus an EIP-191 agent wallet signature. Futures execution requires an EIP-712 Hyperliquid wallet signature. ## Dust Storm Protocol

    On upstream failure, FarmDash returns `ok:false` with a typed degraded state

    and a `warnings` array containing `{ kind: "dust_storm", message: "..." }`. Cached SDK responses may be returned as stale with explicit stale-data age. ## x402 Payment Wall

    When Scout limits are exceeded, FarmDash returns HTTP 402 with

    `code: free_quota_exhausted`, `instruction: STOP_RETRYING`, the UTC reset time,

    upgrade URL, and x402 payment instructions.'
  contact:
    name: FarmDash Engineering
    url: https://www.farmdash.one/agents
  license:
    name: MIT
servers:
- url: https://www.farmdash.one/api
  description: Production
tags:
- name: Intelligence
  description: Trail Heat protocol data and chain analytics
paths:
  /api/status:
    parameters:
    - $ref: '#/components/parameters/X-FarmDash-Installation-ID'
    - $ref: '#/components/parameters/X-FarmDash-Client'
    - $ref: '#/components/parameters/X-FarmDash-Client-Version'
    - $ref: '#/components/parameters/X-FarmDash-Skill-Version'
    get:
      operationId: getPublicSystemStatus
      summary: Get authoritative public system status and agent capability contract
      description: 'Returns the real-time operational status of all 9 Trail Stack lifecycle stages,

        core infrastructure, and venue execution capabilities (e.g. EVM swaps LIVE,

        Hyperliquid perps LIVE, generic intents PREPARATION ONLY, Solana DISCOVERY ONLY).

        Zero authentication required. Autonomous AI agents can query this before

        initiating transactions.'
      tags:
      - Intelligence
      parameters:
      - $ref: '#/components/parameters/X-ClawHub-Skill'
      responses:
        '200':
          description: Public system status and capability contract
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '503':
          description: Major system outage detected
  /v1/agent/status:
    parameters:
    - $ref: '#/components/parameters/X-FarmDash-Installation-ID'
    - $ref: '#/components/parameters/X-FarmDash-Client'
    - $ref: '#/components/parameters/X-FarmDash-Client-Version'
    - $ref: '#/components/parameters/X-FarmDash-Skill-Version'
    get:
      operationId: getAgentStatus
      summary: Get agent feature status and contracts
      description: 'Public status endpoint for agent builders. Returns feature readiness,

        tier gates, data-confidence contract, structured-error contract, and

        deterministic sandbox instructions. This endpoint is not a trading or

        portfolio-data surface.'
      tags:
      - Intelligence
      parameters:
      - $ref: '#/components/parameters/X-ClawHub-Skill'
      responses:
        '200':
          description: Agent status contract
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '405':
          $ref: '#/components/responses/BadRequest'
  /v1/agent/protocols:
    parameters:
    - $ref: '#/components/parameters/X-FarmDash-Installation-ID'
    - $ref: '#/components/parameters/X-FarmDash-Client'
    - $ref: '#/components/parameters/X-FarmDash-Client-Version'
    - $ref: '#/components/parameters/X-FarmDash-Skill-Version'
    get:
      operationId: getProtocolCatalog
      summary: Get catalog protocol directory (discovery heuristic scores)
      description: 'Returns the curated FarmDash protocol catalog with EDITORIAL discovery

        heuristic scores. These are NOT live Trail Heat: values derive from

        static catalog TVL strings, status labels and hand-curated flags

        (methodology catalog-editorial-v1). The canonical quantitative Trail

        Scout tier: top 3 spotlight protocols with 100% unmasked quantitative scores (30 req/day).

        Pioneer/Syndicate: full dataset for the current FarmDash protocol registry (81 protocols at this build).'
      tags:
      - Intelligence
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/X-ClawHub-Skill'
      responses:
        '200':
          description: Protocol dataset
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtocolsResponse'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /v1/trail-heat:
    parameters:
    - $ref: '#/components/parameters/X-FarmDash-Installation-ID'
    - $ref: '#/components/parameters/X-FarmDash-Client'
    - $ref: '#/components/parameters/X-FarmDash-Client-Version'
    - $ref: '#/components/parameters/X-FarmDash-Skill-Version'
    get:
      operationId: getLiveTrailHeat
      summary: Get live or deterministic mock Trail Heat scores
      description: 'Returns DeFiLlama-backed Trail Heat scores with source, confidence, and

        methodology metadata. Aggregate responses also include agent recommendations

        derived from the same live scores. Commercial preference is transparent:

        FarmDash referral routes may move ahead only inside a 5-point Trail Heat

        quality band; materially stronger protocols always win and canonical scores

        are never changed. Campaign activity/eligibility is not inferred from protocol

        activity. Pioneer/Syndicate callers can use `?recommend=N` for a recommendation-only

        response; Scout callers continue to receive the bounded three-protocol spotlight preview

        with recommendations limited to that preview. `?mock=true` returns deterministic demo fixtures that are explicitly marked

        mock and not for trading.'
      tags:
      - Intelligence
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/X-ClawHub-Skill'
      - name: mock
        in: query
        schema:
          type: string
          enum:
          - 'true'
        description: Return deterministic, explicitly non-live demo data.
      - name: recommend
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
        description: Pioneer/Syndicate only — return N live protocol recommendations. Scout remains bounded to its three-protocol spotlight preview. Canonical Trail Heat is the primary signal; only owner-confirmed, non-wallet-bound FarmDash referral routes are eligible for the near-equivalent-quality tiebreaker.
      responses:
        '200':
          description: Live or deterministic mock Trail Heat response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '503':
          description: Typed Trail Heat service degradation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/agent/historical-trailheat:
    parameters:
    - $ref: '#/components/parameters/X-FarmDash-Installation-ID'
    - $ref: '#/components/parameters/X-FarmDash-Client'
    - $ref: '#/components/parameters/X-FarmDash-Client-Version'
    - $ref: '#/components/parameters/X-FarmDash-Skill-Version'
    get:
      operationId: getHistoricalTrailHeat
      summary: Query historical Trail Heat snapshots
      description: 'Requires Pioneer or Syndicate access through the TollBooth. Scout receives

        402 even within its free quota. Requires the trail_heat_snapshots store;

        missing storage or query failures return 503 rather than fabricated history.

        With protocolId, returns that protocol''s daily history; without it, returns

        the latest snapshot per protocol in the requested window. Legacy editorial

        and canonical-live vintages are not quantitatively comparable; inspect

        data_evidence, evidence_vintage and data_quality before trend analysis.'
      tags:
      - Intelligence
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/X-ClawHub-Skill'
      - name: protocolId
        in: query
        required: false
        description: Optional protocol identifier; runtime removes characters outside a-z, A-Z, 0-9 and underscore, then truncates to 64 characters. Omit or send empty for all protocols.
        schema:
          type: string
      - name: days
        in: query
        required: false
        description: Runtime uses parseInt base 10, defaults falsy or invalid results to 30, then clamps to 1 through 365; out-of-range input is normalized, not rejected.
        schema:
          type: integer
          default: 30
      responses:
        '200':
          description: Stored snapshots with explicit scoring provenance
          content:
            application/json:
              schema:
                type: object
                required:
                - snapshots
                - count
                - days
                - score_semantics
                - data_quality
                properties:
                  protocolId:
                    type: string
                    description: Present only for a specific protocol query; sanitized identifier
                  count:
                    type: integer
                  days:
                    type: integer
                    minimum: 1
                    maximum: 365
                  score_semantics:
                    type: string
                  data_quality:
                    type: object
                    required:
                    - mode
                    - vintage_mix_warning
                    properties:
                      mode:
                        type: string
                        enum:
                        - canonical
                        - vintage_mix
                        - legacy_only
                      vintage_mix_warning:
                        type:
                        - string
                        - 'null'
                  snapshots:
                    type: array
                    items:
                      type: object
                      required:
                      - protocolId
                      - protocolName
                      - score
                      - components
                      - metadata
                      - data_evidence
                      - evidence_vintage
                      - snapshotDate
                      properties:
                        protocolId:
                          type: string
                        protocolName:
                          type: string
                        score:
                          type:
                          - number
                          - 'null'
                        components:
                          description: Stored score components; historical rows may be null
                        metadata:
                          description: Stored snapshot metadata; historical rows may be null
                        data_evidence:
                          description: Stored canonical evidence, or null for legacy rows
                        evidence_vintage:
                          type: string
                          enum:
                          - canonical-live
                          - legacy-editorial-heuristic
                        snapshotDate:
                          type: string
                          format: date
        '402':
          description: Pioneer access required or TollBooth payment wall; payment does not change execution authority
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequiredError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '503':
          description: Historical storage is not ready (feature_not_ready) or historical_trailheat_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/agent/prices:
    parameters:
    - $ref: '#/components/parameters/X-FarmDash-Installation-ID'
    - $ref: '#/components/parameters/X-FarmDash-Client'
    - $ref: '#/components/parameters/X-FarmDash-Client-Version'
    - $ref: '#/components/parameters/X-FarmDash-Skill-Version'
    get:
      operationId: getTokenPrices
      summary: Get live token price context
      description: Returns live Alchemy USD prices. Provider failure is a typed ok:false degraded response, never a successful empty or zero price set.
      tags:
      - Intelligence
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/X-ClawHub-Skill'
      - name: symbols
        in: query
        schema:
          type: string
          example: ETH,USDC
        description: Comma-separated token symbols; provide symbols or tokens.
      - name: tokens
        in: query
        schema:
          type: string
          example: base-mainnet:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
        description: Comma-separated network:address pairs; provide symbols or tokens.
      responses:
        '200':
          description: Live token prices with explicit data quality
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '502':
          description: Typed upstream price degradation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Price provider is not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/agent/workflows:
    parameters:
    - $ref: '#/components/parameters/X-FarmDash-Installation-ID'
    - $ref: '#/components/parameters/X-FarmDash-Client'
    - $ref: '#/components/parameters/X-FarmDash-Client-Version'
    - $ref: '#/components/parameters/X-FarmDash-Skill-Version'
    get:
      operationId: listAgentWorkflows
      summary: List supervised workflow templates
      description: Public catalog of planning and supervised workflow templates. Catalog registration does not enable the execution capabilities used by a workflow.
      tags:
      - Intelligence
      parameters:
      - $ref: '#/components/parameters/X-ClawHub-Skill'
      - name: filter
        in: query
        schema:
          type: string
        description: Optional case-insensitive catalog filter.
      responses:
        '200':
          description: Workflow catalog
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /v1/agent/chain-breakdown:
    parameters:
    - $ref: '#/components/parameters/X-FarmDash-Installation-ID'
    - $ref: '#/components/parameters/X-FarmDash-Client'
    - $ref: '#/components/parameters/X-FarmDash-Client-Version'
    - $ref: '#/components/parameters/X-FarmDash-Skill-Version'
    get:
      operationId: getChainBreakdown
      summary: Get protocol distribution by chain
      description: 'Aggregates the protocol directory by blockchain network.

        Returns per-chain protocol counts, confirmed airdrops, points programs,

        and category coverage.'
      tags:
      - Intelligence
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/X-ClawHub-Skill'
      responses:
        '200':
          description: Chain breakdown
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainBreakdownResponse'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  parameters:
    X-FarmDash-Client-Version:
      name: X-FarmDash-Client-Version
      in: header
      required: false
      description: Optional analytics client version; never security evidence.
      schema:
        type: string
        maxLength: 64
        pattern: ^[A-Za-z0-9._+-]{1,64}$
    X-FarmDash-Skill-Version:
      name: X-FarmDash-Skill-Version
      in: header
      required: false
      description: Optional event-touch analytics skill version, alongside X-ClawHub-Skill; never security evidence.
      schema:
        type: string
        maxLength: 64
        pattern: ^[A-Za-z0-9._+-]{1,64}$
    X-FarmDash-Installation-ID:
      name: X-FarmDash-Installation-ID
      in: header
      required: false
      description: Optional analytics-only locally generated UUIDv4 installation hint. Stored only as a domain-separated salted hash. Not authentication, principal proof, quota, payment, wallet ownership, delegation or transaction authority. Omission changes no functionality.
      schema:
        type: string
        format: uuid
        pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
    X-FarmDash-Client:
      name: X-FarmDash-Client
      in: header
      required: false
      description: Optional untrusted analytics client hint; never security evidence.
      schema:
        type: string
        enum:
        - mcp
        - ts_agent_kit
        - python_agent_kit
        - public_client
        - webapp
    X-ClawHub-Skill:
      name: X-ClawHub-Skill
      in: header
      required: false
      schema:
        type: string
        pattern: ^[a-zA-Z0-9-]{1,128}$
        example: farmdash-signal-architect
      description: 'ClawHub skill attribution. An installed FarmDash skill sends its canonical skill slug (e.g. farmdash-signal-architect) on every FarmDash API request so anonymous Scout usage can be attributed to the skill that drove it. Optional and analytics-only: absence never blocks a request, and malformed values are ignored. This is a skill identity, never a wallet address, API key, or user ID.'
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        ok:
          type: boolean
          example: false
        error:
          type: string
        code:
          type: string
        message:
          type: string
        retryable:
          type: boolean
        request_id:
          type: string
        details:
          type: object
          additionalProperties: true
    PaymentRequiredError:
      type: object
      properties:
        ok:
          type: boolean
          example: false
        error:
          type: string
          example: payment_required
        code:
          type: string
          description: '`free_quota_exhausted` when the shared Scout allowance is spent; otherwise `payment_required`.'
          example: free_quota_exhausted
        message:
          type: string
        instruction:
          type: string
          enum:
          - STOP_RETRYING
          description: Present when an exhausted free caller must not repeat the same unpaid request.
        retry_same_request:
          type: boolean
          example: false
        next_action:
          type: string
          example: Wait for your quota reset, upgrade your plan, or use x402 paid access.
        quota:
          type: object
          properties:
            tier:
              type: string
              example: scout
            remaining:
              type: integer
              example: 0
            reset_at:
              type: string
              format: date-time
        abuse_notice:
          type: string
          example: Repeated automated requests while quota is exhausted may result in temporary or permanent API blocking.
        retryable:
          type: boolean
        upgrade_url:
          type: string
          format: uri
        direct_upgrade_url:
          type: string
          format: uri
        rate_limit:
          type: object
          additionalProperties: true
        developer_sandbox:
          type: object
          additionalProperties: true
        payment_required:
          type: object
          properties:
            amount:
              type: string
              example: 0.01 USDC
            chain:
              type: string
              example: Base
            destination:
              type: string
              example: '0xb0Ed0d7bca24BBaD635B977C2efbE06742e33377'
            token:
              type: string
            chainId:
              type: integer
              example: 8453
    ChainBreakdownResponse:
      type: object
      required:
      - tier
      - data
      properties:
        tier:
          $ref: '#/components/schemas/Tier'
        status:
          type: string
        message:
          type: string
        direct_upgrade_url:
          type: string
          format: uri
        data:
          type: object
          properties:
            chains:
              type: array
              items:
                $ref: '#/components/schemas/ChainBreakdownItem'
            summary:
              $ref: '#/components/schemas/ChainBreakdownSummary'
    Tier:
      type: string
      enum:
      - scout
      - pioneer
      - syndicate
    ChainBreakdownSummary:
      type: object
      properties:
        total_chains:
          type: integer
        total_protocols:
          oneOf:
          - type: integer
          - type: string
        dominant_chain:
          type: string
          nullable: true
        dominant_chain_pct:
          oneOf:
          - type: number
          - type: string
    ChainBreakdownItem:
      type: object
      properties:
        chain:
          type: string
        protocol_count:
          oneOf:
          - type: integer
          - type: string
        pct_of_total:
          oneOf:
          - type: number
          - type: string
        confirmed_airdrops:
          oneOf:
          - type: integer
          - type: string
        points_programs:
          oneOf:
          - type: integer
          - type: string
        categories:
          type: array
          items:
            type: string
    ProtocolsResponse:
      type: object
      required:
      - tier
      - count
      - data
      properties:
        tier:
          $ref: '#/components/schemas/Tier'
        count:
          type: integer
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProtocolItem'
        status:
          type: string
        message:
          type: string
        direct_upgrade_url:
          type: string
          format: uri
        total_protocols_available:
          type: integer
    ProtocolItem:
      type: object
      properties:
        protocol_name:
          type: string
        discovery_heuristic_score:
          oneOf:
          - type: number
          - type: string
            description: Encrypted for scout tier
          description: Catalog editorial heuristic (methodology catalog-editorial-v1). NOT live Trail Heat — canonical quantitative scores live at /v1/trail-heat.
        discovery_methodology:
          type: string
        sybil_risk:
          type: string
        tvl:
          type: string
        category:
          type: string
          enum:
          - Perps
          - Lending
          - Dex
          - L2
          - Bridge
          - Restaking
          - HyperEVM
          - Infra
          - Wallet
          - Testnet
        status:
          type: string
          enum:
          - Confirmed Airdrop
          - Points Program
          - Speculative
        chains:
          type: array
          items:
            type: string
        recommended_agent_deploy_link:
          type: string
          format: uri
  responses:
    RateLimitExceeded:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until rate limit resets
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentRequired:
      description: Free-tier limit exceeded — x402 payment required
      headers:
        X-Payment-Required:
          schema:
            type: string
        X-Payment-Address:
          schema:
            type: string
          description: Treasury wallet (USDC on Base)
        X-Payment-Token:
          schema:
            type: string
          description: USDC contract on Base
        X-Payment-Amount:
          schema:
            type: string
          description: Amount in token decimals (990000 = 0.99 USDC)
        X-Payment-Chain-Id:
          schema:
            type: string
          description: 8453 (Base)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentRequiredError'
  headers:
    X-Request-ID:
      description: Unique request trace ID for debugging and support
      schema:
        type: string
        format: uuid
    X-RateLimit-Remaining:
      description: Remaining requests in the current window
      schema:
        type: string
    X-RateLimit-Reset:
      description: UTC epoch seconds when the rate limit window resets
      schema:
        type: string
    X-RateLimit-Limit:
      description: Maximum requests allowed in the current window
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Pioneer or Syndicate API key
x-agent-use-cases:
- id: bounded-autopilot
  name: Bounded Autopilot
  tier: Syndicate
  cadence: Every 5 minutes
  purpose: Run an always-on loop inside explicit budgets, allowlists, cooldowns, quote freshness, and local-signing requirements.
  primaryTools:
  - agent_onboard
  - create_session
  - configure_autopilot
  - autopilot_cycle
  - session_heartbeat
  stopConditions:
  - Budget, allowlist, cooldown, quote freshness, or risk bound is violated.
  - Required local EIP-191 or EIP-712 signature is missing.
  - Realized performance degrades enough to require analysis_only mode.
- id: airdrop-rotation
  name: Airdrop Rotation Desk
  tier: Pioneer
  cadence: Daily or event-driven
  purpose: Watch Trail Heat, snapshots, multiplier changes, wallet health, and costs before entering, waiting, rotating, or exiting.
  primaryTools:
  - get_trail_heat
  - get_historical_trailheat
  - get_agent_events
  - simulate_points
  - get_swap_quote
  - simulate_swap_execution
  stopConditions:
  - Expected point edge is unclear or negative after fees and gas.
  - Sybil risk exceeds the configured threshold.
  - User constraints do not allow the target chain or protocol.
- id: cross-chain-roi
  name: Cross-Chain ROI Gate
  tier: Pioneer
  cadence: Before any bridge
  purpose: Bridge only when net expected edge remains positive after bridge fee, gas, slippage, and execution risk buffer.
  primaryTools:
  - get_chain_breakdown
  - get_wallet_balances
  - get_token_prices
  - get_swap_quote
  - simulate_swap_execution
  - optimize_portfolio
  stopConditions:
  - netEdgeUsd is not positive.
  - Quote age exceeds the configured freshness limit.
  - Target chain is not allowlisted.


# --- truncated at 32 KB (34 KB total) ---
# Full source: https://artifacts.apis.io/farmdash/openapi/farmdash-intelligence-api-openapi.yml