FarmDash Agent Hub Risk API

openapi: 3.2.0
info:
  title: FarmDash Agent Risk 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.'
  contact:
    name: FarmDash Engineering
    url: https://www.farmdash.one/agents
  license:
    name: MIT
servers:
- url: https://www.farmdash.one/api
  description: Production
tags:
- name: Risk
  description: Pre-trade risk analysis, alerts, and execution guardrails
paths:
  /v1/simulate:
    post:
      operationId: simulateSwapExecution
      summary: Simulate a wallet-bound swap intent
      description: 'Mandatory pre-execution simulation gate for Signal Architect. The caller

        submits the `intent_id` returned by `/agents/quote` plus the signing wallet.

        FarmDash simulates the quote intent, caches the result for 60 seconds, and

        returns a `simulation_id` that `/agents/swap` requires.'
      tags:
      - Risk
      security:
      - bearerAuth: []
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwapSimulationRequest'
      responses:
        '200':
          description: Simulation report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwapSimulationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '409':
          description: Intent and wallet mismatch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /v1/agent/risk-sentinel:
    get:
      operationId: getRiskSentinelInfo
      summary: Describe Risk Sentinel usage
      description: 'Returns a lightweight usage guide for the standalone risk-analysis endpoint.

        Use POST to inspect allowance state, token/bridge/contract risks, depeg checks,

        health-factor alerts, quote decay, and positive-net-edge enforcement.'
      tags:
      - Risk
      security:
      - bearerAuth: []
      - {}
      responses:
        '200':
          description: Usage guide
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  description:
                    type: string
                  usage:
                    type: string
        '402':
          $ref: '#/components/responses/PaymentRequired'
    post:
      operationId: analyzeRiskSentinel
      summary: Analyze a route or account with Risk Sentinel
      description: 'Accepts either a full swap-shaped payload or manual health/net-edge inputs.

        When swap fields are present, FarmDash auto-selects a route, computes

        Execution Alpha diagnostics, and returns a full Risk Sentinel report.'
      tags:
      - Risk
      security:
      - bearerAuth: []
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RiskSentinelRequest'
      responses:
        '200':
          description: Risk analysis
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskSentinelResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  schemas:
    RiskSentinelRequest:
      type: object
      description: Provide either manual health/net-edge inputs or a full swap-shaped request for route-aware analysis.
      properties:
        fromChainId:
          type: integer
          enum:
          - 1
          - 10
          - 137
          - 8453
          - 42161
          - 59144
        toChainId:
          type: integer
          enum:
          - 1
          - 10
          - 137
          - 8453
          - 42161
          - 59144
        fromToken:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
        toToken:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
        fromAmount:
          type: string
          pattern: ^\d+$
        walletAddress:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
        toAddress:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
        protocol:
          type: string
          enum:
          - lifi
          - zerox
          - x402
        slippage:
          type: number
        expectedUpsideUsd:
          type: number
        riskBufferUsd:
          type: number
        healthFactor:
          type: number
        liquidationBufferPct:
          type: number
        protocolFeeUsd:
          type: number
        gasUsd:
          type: number
        bridgeFeeUsd:
          type: number
        enforcePositive:
          type: boolean
        safetyMode:
          $ref: '#/components/schemas/SwapSafetyMode'
    PaymentRequiredError:
      type: object
      properties:
        ok:
          type: boolean
          example: false
        error:
          type: string
          example: payment_required
        code:
          type: string
          example: payment_required
        message:
          type: string
        retryable:
          type: boolean
        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
    RouteCandidate:
      type: object
      properties:
        protocol:
          $ref: '#/components/schemas/SupportedProtocol'
        estimatedOutput:
          type: string
        feeAmountUsd:
          type: number
        gasEstimateUsd:
          type: number
          nullable: true
        bridgeFeeUsd:
          type: number
          nullable: true
        routeRiskScore:
          type: number
        selected:
          type: boolean
    RiskSentinelResponse:
      type: object
      properties:
        ok:
          type: boolean
        mode:
          type: string
          enum:
          - manual
          - quoted
        selectedProtocol:
          allOf:
          - $ref: '#/components/schemas/SupportedProtocol'
          nullable: true
        executionAlpha:
          allOf:
          - $ref: '#/components/schemas/ExecutionAlphaReport'
          nullable: true
        riskReport:
          allOf:
          - $ref: '#/components/schemas/SwapRiskReport'
          nullable: true
        quotePreview:
          allOf:
          - $ref: '#/components/schemas/SwapResult'
          nullable: true
        health:
          allOf:
          - $ref: '#/components/schemas/HealthCheck'
          nullable: true
        netEdge:
          allOf:
          - $ref: '#/components/schemas/NetEdgeAnalysis'
          nullable: true
        flags:
          type: array
          items:
            $ref: '#/components/schemas/RiskFlag'
        shouldHalt:
          type: boolean
    SwapRiskReport:
      type: object
      properties:
        flags:
          type: array
          items:
            $ref: '#/components/schemas/RiskFlag'
        approval:
          allOf:
          - $ref: '#/components/schemas/AllowanceStatus'
          nullable: true
        pegChecks:
          type: array
          items:
            $ref: '#/components/schemas/PegCheck'
        health:
          allOf:
          - $ref: '#/components/schemas/HealthCheck'
          nullable: true
        shouldHalt:
          type: boolean
        haltReasons:
          type: array
          items:
            type: string
    RiskFlag:
      type: object
      required:
      - code
      - category
      - severity
      - title
      - message
      properties:
        code:
          type: string
        category:
          type: string
          enum:
          - approval
          - bridge
          - contract
          - token
          - health
          - execution
        severity:
          $ref: '#/components/schemas/RiskSeverity'
        title:
          type: string
        message:
          type: string
        metadata:
          type: object
          additionalProperties: true
    NetEdgeAnalysis:
      type: object
      properties:
        expectedUpsideUsd:
          type: number
          nullable: true
        protocolFeeUsd:
          type: number
        gasUsd:
          type: number
        bridgeFeeUsd:
          type: number
        riskBufferUsd:
          type: number
        totalCostUsd:
          type: number
        netEdgeUsd:
          type: number
          nullable: true
        positive:
          type: boolean
          nullable: true
        enforced:
          type: boolean
    SwapTxData:
      type: object
      required:
      - to
      - data
      - value
      - chainId
      properties:
        to:
          type: string
          description: Protocol contract address (NOT FarmDash)
        data:
          type: string
          description: Encoded calldata
        value:
          type: string
          description: Native token value in wei
        chainId:
          type: integer
    SwapSafetyMode:
      type: string
      enum:
      - strict
      - balanced
    SupportedProtocol:
      type: string
      enum:
      - lifi
      - zerox
      - x402
      - okx
    SwapSimulationResponse:
      type: object
      required:
      - ok
      - simulation_id
      - intent_id
      - success
      - gas_used
      - gas_cost_usd
      - output_amount
      - mev_risk
      - valid_until
      - wallet_address
      - selected_protocol
      - required_for_execution
      properties:
        ok:
          type: boolean
          example: true
        simulation_id:
          type: string
          example: sim_9b2e
        intent_id:
          type: string
        success:
          type: boolean
        gas_used:
          type: number
        gas_cost_usd:
          type: number
        output_amount:
          type: string
        price_impact_pct:
          type: number
          nullable: true
        mev_risk:
          type: string
          enum:
          - low
          - medium
          - high
        revert_reason:
          type: string
          nullable: true
        valid_until:
          type: string
          format: date-time
        wallet_address:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
        selected_protocol:
          $ref: '#/components/schemas/SupportedProtocol'
        tx_fingerprint:
          type: string
        request_fingerprint:
          type: string
        provider:
          type: string
        cached:
          type: boolean
        required_for_execution:
          type: boolean
          const: true
    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
    SwapResult:
      type: object
      required:
      - protocol
      - estimatedOutput
      - feeBps
      - feeAmountUSD
      - gasEstimate
      - txData
      - expiresAt
      properties:
        protocol:
          $ref: '#/components/schemas/SupportedProtocol'
        estimatedOutput:
          type: string
        feeBps:
          type: integer
        feeAmountUSD:
          type: string
        feeEventId:
          type: string
          format: uuid
          description: Use with /agents/confirm to confirm settlement
        gasEstimate:
          type: string
        txData:
          $ref: '#/components/schemas/SwapTxData'
        expiresAt:
          type: integer
        allowanceTarget:
          type: string
          nullable: true
        gasEstimateUsd:
          type: number
          nullable: true
        bridgeFeeUsd:
          type: number
          nullable: true
        simulation:
          type: object
          additionalProperties: true
        executionAlpha:
          $ref: '#/components/schemas/ExecutionAlphaReport'
        riskReport:
          $ref: '#/components/schemas/SwapRiskReport'
        confirmUrl:
          type: string
          example: /api/agents/confirm
    QuoteDecayMetrics:
      type: object
      properties:
        previousObservedAt:
          type: integer
          nullable: true
        quoteAgeMs:
          type: integer
          nullable: true
        outputDecayBps:
          type: number
        gasIncreaseBps:
          type: number
        severity:
          $ref: '#/components/schemas/QuoteDecaySeverity'
    HealthCheck:
      type: object
      properties:
        healthFactor:
          type: number
          nullable: true
        liquidationBufferPct:
          type: number
          nullable: true
        alertLevel:
          type: string
          enum:
          - none
          - warning
          - critical
        shouldHalt:
          type: boolean
    QuoteDecaySeverity:
      type: string
      enum:
      - none
      - low
      - medium
      - high
    AllowanceStatus:
      type: object
      properties:
        spender:
          type: string
          nullable: true
        allowance:
          type: string
          nullable: true
        requiredAmount:
          type: string
        approvalNeeded:
          type: boolean
        overApproved:
          type: boolean
        source:
          type: string
          enum:
          - onchain
          - quote_fallback
          - unavailable
    SwapSimulationRequest:
      type: object
      required:
      - intent_id
      - wallet_address
      properties:
        intent_id:
          type: string
          description: Wallet-bound quote intent returned by /agents/quote
          example: fd_intent_7f3a
        wallet_address:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: Signing wallet for the simulated execution
    ExecutionAlphaReport:
      type: object
      properties:
        selectedProtocol:
          $ref: '#/components/schemas/SupportedProtocol'
        routeReason:
          type: string
        mevProtection:
          type: object
          properties:
            safetyMode:
              $ref: '#/components/schemas/SwapSafetyMode'
            actualSlippageBps:
              type: integer
            maxRecommendedSlippageBps:
              type: integer
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/RouteCandidate'
        quoteDecay:
          $ref: '#/components/schemas/QuoteDecayMetrics'
        netEdge:
          $ref: '#/components/schemas/NetEdgeAnalysis'
    PegCheck:
      type: object
      properties:
        tokenAddress:
          type: string
        symbol:
          type: string
        reference:
          type: string
          enum:
          - USD
          - ETH
        priceUsd:
          type: number
          nullable: true
        referencePriceUsd:
          type: number
          nullable: true
        deviationPct:
          type: number
          nullable: true
        alert:
          type: boolean
    RiskSeverity:
      type: string
      enum:
      - low
      - medium
      - high
      - critical
  headers:
    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
    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
  responses:
    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'
    BadRequest:
      description: Invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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'
  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.