FarmDash Agent Hub Agent API

openapi: 3.2.0
info:
  title: FarmDash Agent 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: Agent
paths:
  /v1/agent/futures/reconcile-order:
    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'
    post:
      operationId: reconcilePerpOrder
      summary: Reconcile one Hyperliquid order from authoritative venue evidence
      description: 'Read-only and zero-custody: signs nothing, submits nothing, and never retries

        an order. Durable order/fill evidence uses the existing idempotent accounting

        path; balances are not execution evidence. agentAddress is the venue API-wallet

        signer, not the session agent. accountAddress identifies its delegated owner.

        Known bounded reservations are discovered by account, network, market and OID.

        Optional controlActionId selects one exact durable action for cancellation or

        unknown-submission recovery. Selection is not proof of OID linkage; unproven

        submissions remain unknown and liability stays held. For a batch cancellation,

        reconcile every signed target OID. A bounded reservation result is policy

        bookkeeping, not proof of a fill, final cancellation or recognized revenue.'
      security:
      - bearerAuth: []
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReconcileOrderRequest'
      responses:
        '200':
          description: Authoritative venue evidence recorded durably; bounded context is present only when matching reservations exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcileOrderResponse'
        '400':
          description: Invalid input or signer/account authority relationship
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcileOrderError'
        '402':
          description: Commercial API capacity payment required; payment is not execution authority
        '409':
          description: controlActionId does not identify one unique durable action for this account, network and market; no liability released
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcileOrderError'
        '413':
          description: Request body exceeds 1 MB
        '429':
          description: API rate limit exceeded
        '502':
          description: Reconciliation unavailable; no execution or liability release inferred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcileOrderError'
        '503':
          description: Venue evidence or durable reconciliation unavailable; inspect durableEvidence before claiming persistence, and never resubmit automatically
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcileOrderError'
      tags:
      - Agent
components:
  schemas:
    FuturesBuilderFeeReconciliation:
      type: object
      required:
      - state
      - builderFeeTotal
      - fillCountWithBuilderFee
      - feeToken
      - venueTotal
      - nonBuilderVenueFee
      - recipient
      - signedTenthsBps
      - reason
      - fills
      properties:
        state:
          type: string
          enum:
          - exact
          - absent
          - ambiguous
          - unavailable
        builderFeeTotal:
          type: string
          nullable: true
        fillCountWithBuilderFee:
          type: integer
        feeToken:
          type: string
          nullable: true
        venueTotal:
          type: string
          nullable: true
        nonBuilderVenueFee:
          type: string
          nullable: true
        recipient:
          type: string
          nullable: true
        signedTenthsBps:
          type: string
          nullable: true
        reason:
          type: string
          nullable: true
        fills:
          type: array
          items:
            $ref: '#/components/schemas/FuturesBuilderFeeFill'
    FuturesReconciliationState:
      type: string
      enum:
      - submitted
      - resting
      - partially_filled
      - fully_filled
      - canceled
      - venue_canceled
      - rejected
      - unknown
      - ambiguous
    FuturesBuilderFeeFill:
      type: object
      required:
      - fillId
      - fillHash
      - observedBuilderFee
      - expectedBuilderFee
      - builderFeeToken
      - nonBuilderVenueFee
      - state
      - reason
      properties:
        fillId:
          type: integer
        fillHash:
          type: string
        observedBuilderFee:
          type: string
          nullable: true
        expectedBuilderFee:
          type: string
          nullable: true
        builderFeeToken:
          type: string
          nullable: true
        nonBuilderVenueFee:
          type: string
          nullable: true
        state:
          type: string
          enum:
          - exact
          - absent
          - ambiguous
          - unavailable
        reason:
          type: string
          nullable: true
    FuturesOrderReconciliation:
      allOf:
      - $ref: '#/components/schemas/FuturesOrderReconciliationEvidence'
      - type: object
        required:
        - state
        - evidence
        properties:
          state:
            $ref: '#/components/schemas/FuturesReconciliationState'
          evidence:
            $ref: '#/components/schemas/FuturesOrderReconciliationEvidence'
    ReconcileOrderRequest:
      type: object
      additionalProperties: false
      required:
      - agentAddress
      - coin
      - orderId
      properties:
        agentAddress:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: Venue API-wallet signer; never replaced by the session agent
        accountAddress:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: Delegated equity owner; defaults to agentAddress
        coin:
          type: string
          pattern: ^[a-zA-Z0-9]{1,16}$
          description: Default Hyperliquid perp market symbol, normalized uppercase
        orderId:
          type: integer
          minimum: 1
          maximum: 9007199254740991
        intentHash:
          type: string
          nullable: true
          pattern: ^[a-f0-9]{64}$
          description: Optional submission provenance selector; caller hash alone is not evidence
        controlActionId:
          type: string
          format: uuid
          pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
          description: Optional exact durable bounded control action selector, not authority or proof of OID linkage
    ReconcileOrderError:
      type: object
      description: Validation, conflict or degraded error. Established venue truth may accompany a persistence/core failure; missing durableEvidence never proves persistence. No automatic action resubmission.
      properties:
        ok:
          type: boolean
          enum:
          - false
        code:
          type: string
        error:
          oneOf:
          - type: string
          - type: object
            additionalProperties: true
        reason:
          type: string
        retryable:
          type: boolean
        degraded:
          type: object
          additionalProperties: true
        warnings:
          type: array
          items:
            type: object
            additionalProperties: true
        reconciliation:
          $ref: '#/components/schemas/FuturesOrderReconciliation'
        builderFees:
          $ref: '#/components/schemas/FuturesBuilderFeeReconciliation'
        durableEvidence:
          type: object
          required:
          - recorded
          properties:
            recorded:
              type: boolean
            record:
              type: object
              nullable: true
              additionalProperties: true
    BoundedFuturesReconciliation:
      type: object
      required:
      - actionId
      - result
      properties:
        actionId:
          type: string
          format: uuid
        result:
          oneOf:
          - $ref: '#/components/schemas/BoundedFuturesReservation'
          - type: object
            additionalProperties: false
            required:
            - bounded
            properties:
              bounded:
                type: boolean
                enum:
                - false
    FuturesReconciledFill:
      type: object
      required:
      - fillId
      - fillHash
      - side
      - size
      - price
      - notional
      - fee
      - feeToken
      - sizeRaw
      - priceRaw
      - feeRaw
      - builderFeeRaw
      - filledAt
      properties:
        fillId:
          type: integer
        fillHash:
          type: string
        side:
          type: string
          enum:
          - buy
          - sell
        size:
          type: number
        price:
          type: number
        notional:
          type: number
        fee:
          type: number
        feeToken:
          type: string
        sizeRaw:
          type: string
          nullable: true
        priceRaw:
          type: string
          nullable: true
        feeRaw:
          type: string
          nullable: true
        builderFeeRaw:
          type: string
          nullable: true
        filledAt:
          type: integer
          description: Unix milliseconds
    ReconcileOrderDurableEvidence:
      type: object
      required:
      - recorded
      - note
      properties:
        recorded:
          type: boolean
          enum:
          - true
        record:
          type: object
          nullable: true
          additionalProperties: true
        note:
          type: string
    ReconcileOrderResponse:
      type: object
      required:
      - ok
      - reconciliation
      - builderFees
      - durableEvidence
      - evidenceSources
      - timestamp
      properties:
        ok:
          type: boolean
          enum:
          - true
        reconciliation:
          $ref: '#/components/schemas/FuturesOrderReconciliation'
        boundedReconciliation:
          type: array
          description: Optional; omitted when no durable bounded actions match. An accepted reservation is not final venue cancellation.
          items:
            $ref: '#/components/schemas/BoundedFuturesReconciliation'
        builderFees:
          $ref: '#/components/schemas/FuturesBuilderFeeReconciliation'
        durableEvidence:
          $ref: '#/components/schemas/ReconcileOrderDurableEvidence'
        evidenceSources:
          type: object
          required:
          - orderStatus
          - fills
          - methodology
          - balanceDeltasUsed
          properties:
            orderStatus:
              type: string
              enum:
              - hyperliquid_order_status
            fills:
              type: string
              enum:
              - hyperliquid_user_fills
            methodology:
              type: string
              enum:
              - direct_venue_evidence_only
            balanceDeltasUsed:
              type: boolean
              enum:
              - false
        timestamp:
          type: integer
          description: Unix milliseconds
    BoundedFuturesReservation:
      type: object
      description: Durable reservation row returned by FuturesPolicyService; not proof of execution, final cancellation or revenue
      required:
      - id
      - grant_id
      - action_id
      - network
      - account_address
      - coin
      - intent_hash
      - signed_action_hash
      - venue_order_id
      - status
      - dispatched_at
      properties:
        id:
          type: string
          format: uuid
        grant_id:
          type: string
          format: uuid
        action_id:
          type: string
          format: uuid
        network:
          type: string
          enum:
          - mainnet
          - testnet
        account_address:
          type: string
        coin:
          type: string
        intent_hash:
          type: string
        signed_action_hash:
          type: string
        venue_order_id:
          type: integer
          nullable: true
        status:
          type: string
          enum:
          - submitted
          - accepted
          - held_ambiguous
          - reconciled
          - released
        dispatched_at:
          type: string
          format: date-time
        scope:
          type: string
          enum:
          - futures.open
          - futures.reduce
          - futures.close
          - futures.cancel
          - futures.protective_order
        venue_nonce:
          type: integer
        requested_notional_usd:
          oneOf:
          - type: number
          - type: string
        new_risk_usd:
          oneOf:
          - type: number
          - type: string
        risk_reducing:
          type: boolean
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        evidence:
          type: object
          nullable: true
          additionalProperties: true
        cancel_target_evidence:
          type: object
          additionalProperties: true
    FuturesOrderReconciliationEvidence:
      type: object
      required:
      - accountOwner
      - signerAddress
      - perpDex
      - coin
      - orderId
      - intentHash
      - clientOrderId
      - side
      - orderSize
      - orderPrice
      - venueStatus
      - venueReportedFilledSize
      - reconciliationState
      - filledSize
      - filledNotional
      - avgFillPrice
      - venueFee
      - venueFeeToken
      - fillCount
      - terminal
      - reason
      - fills
      properties:
        accountOwner:
          type: string
        signerAddress:
          type: string
        perpDex:
          type: string
        coin:
          type: string
        orderId:
          type: integer
        intentHash:
          type: string
          nullable: true
        clientOrderId:
          type: string
          nullable: true
        side:
          type: string
          nullable: true
          enum:
          - buy
          - sell
          - null
        orderSize:
          type: number
          nullable: true
        orderPrice:
          type: number
          nullable: true
        venueStatus:
          type: string
          nullable: true
        venueReportedFilledSize:
          type: number
          nullable: true
        reconciliationState:
          $ref: '#/components/schemas/FuturesReconciliationState'
        filledSize:
          type: number
        filledNotional:
          type: number
        avgFillPrice:
          type: number
          nullable: true
        venueFee:
          type: number
        venueFeeToken:
          type: string
          nullable: true
        fillCount:
          type: integer
        terminal:
          type: boolean
        reason:
          type: string
          nullable: true
        fills:
          type: array
          items:
            $ref: '#/components/schemas/FuturesReconciledFill'
  parameters:
    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-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-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-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}$
  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.
- id: perps-hedge
  name: Perps Hedge Co-Pilot
  tier: Syndicate
  cadence: Before exposure changes
  purpose: Evaluate whether a farming position needs a Hyperliquid hedge, with no_trade as a valid outcome.
  primaryTools:
  - scan_funding_rates
  - scan_market_conditions
  - get_futures_account
  - analyze_futures_strategy
  - calculate_position_size
  stopConditions:
  - Research gate expires.
  - Strategy confidence, liquidity, jurisdiction, or guardrails do not support execution.
  - Daily loss or drawdown limit is reached.
x-farmdash-capability-truth:
  spot.USER_SIGNED:
    status: operational
    prerequisite: Healthy execution governor, quote provider, RPC and durable receipt store; customer signs and submits.
  spot.BOUNDED_AUTONOMOUS:
    status: operational
    prerequisite: Owner-signed EVM grant, exact simulation/calldata binding, durable budget and customer-local signer authority.
  futures.USER_SIGNED:
    status: operational
    prerequisite: Venue account ownership, local action signature, builder approval, risk/research gates and durable order control.
  futures.BOUNDED_AUTONOMOUS:
    status: operational
    prerequisite: Authenticated owner-bound futures policy, authorized local API-wallet signature, durable nonce/budget/order controls.
  solana.USER_SIGNED:
    status: operational
    prerequisite: Native Jupiter/RPC route, durable preparation and finality store; customer signs and broadcasts.
  solana.BOUNDED_AUTONOMOUS:
    status: operational
    prerequisite: Native owner-signed Solana policy; local key must be an actual required transaction signer. Policy creates no on-chain authority.
  ERC4337_SERVER_SUBMISSION:
    status: preparation_only
    prerequisite: Qualified tenant/account authorization and session-key policy enforcement on public forwarding, configured bundler, durable claims and verified receipt integration.
  GENERIC_SERVER_INTENT_EXECUTION:
    status: preparation_only
    prerequisite: Trusted executable adapter, exact signed-transaction binding and canonical receipt verifier.
  MEE:
    status: preparation_only
    prerequisite: Production coordinator and authoritative source/destination receipt verifier.
  ACP:
    status: deployment_prerequisite
    prerequisite: AcpReadinessService paidWorkflowReady, evaluator/client identities, migrations, funding/finality workers and Base RPC.
x-provenance:
  method: harvested
  publisher: FarmDash Agent Hub
  source: https://www.farmdash.one/agents/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)