Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: FarmDash Agent Account 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: Account
description: Hyperliquid account state and risk management
paths:
/v1/agent/billing-history:
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: getBillingHistory
summary: Get your subscription state and payment history
description: 'Billing-portal-lite for paid agents. Requires a stored Pioneer or
Syndicate API key (the key is bound to the paying wallet). Returns the
current subscription state (tier, expiry, auto_renew=false — prepaid
30-day terms) plus the append-only payment ledger: one row per
verified on-chain USDC payment, newest first. Renewals append rows;
history is never overwritten.'
tags:
- Account
security:
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/X-ClawHub-Skill'
responses:
'200':
description: Subscription state and payment ledger
content:
application/json:
schema:
type: object
required:
- ok
- wallet
- subscription
- payments
properties:
ok:
type: boolean
wallet:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
subscription:
type: object
properties:
tier:
type: string
nullable: true
expires_at:
type: string
format: date-time
nullable: true
active:
type: boolean
auto_renew:
type: boolean
payments:
type: array
items:
type: object
properties:
kind:
type: string
tier:
type: string
nullable: true
amount_usdc:
type: number
nullable: true
tx_hash:
type: string
nullable: true
chain_id:
type: integer
nullable: true
verified_at:
type: string
format: date-time
created_at:
type: string
format: date-time
'402':
description: Payment required (free tier has no billing history)
'403':
description: Pioneer or Syndicate subscription required
'503':
description: Billing ledger temporarily unavailable
/agents/vouch:
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: vouchForAgent
summary: Cast a signed weighted Trail Cred vouch
description: 'TollBooth rate limits apply; a paid bearer key is optional, not signer proof.
Sign EIP-191 personal_sign over FARMDASH_VOUCH:{lowercase targetAddress}:{nonce}.
With signatureType=eip712, sign AgentVouch(targetAddress address, nonce string)
under domain name FarmDash, version 1, chainId 1 instead. The recovered signer
is the voucher; no caller-supplied voucher address is accepted as authority.
The voucher must already have at least one swap in fee_events. Rejects self
vouches and seed/demo targets; permits at most 5 vouches per address per 24 hours.
Each voucher/target pair is idempotent; duplicate upserts do not replace weight.
Requires the fee_events, agent_vouches and agent_reputation stores. Paying for
API access does not satisfy signer proof or the swap prerequisite.'
tags:
- Account
security:
- {}
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/X-ClawHub-Skill'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- targetAddress
- nonce
- signature
properties:
targetAddress:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
description: Target agent wallet; normalized lowercase before signature recovery
nonce:
type: string
minLength: 1
description: Millisecond timestamp string parsed with parseInt base 10; at most 60 seconds old and at most 5 seconds in the future. Freshness-only, not persisted; pair upsert is idempotent.
signature:
type: string
minLength: 1
description: Wallet signature verified by EIP-191 recovery by default, or EIP-712 recovery when explicitly selected
signatureType:
type: string
enum:
- eip191
- eip712
default: eip191
description: Supported signing modes; omission uses EIP-191
responses:
'200':
description: Vouch pair recorded idempotently
content:
application/json:
schema:
type: object
required:
- ok
- voucher
- target
- weight
properties:
ok:
type: boolean
const: true
voucher:
type: string
pattern: ^0x[a-f0-9]{40}$
target:
type: string
pattern: ^0x[a-f0-9]{40}$
weight:
type: number
minimum: 0.01
'400':
description: Missing fields, invalid target/nonce, stale_nonce, self_vouch or demo_target
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: invalid_signature or unrecoverable_signer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
description: vouch_sybil_gate — recovered voucher has no recorded swap in fee_events
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
$ref: '#/components/responses/RateLimitExceeded'
'503':
description: vouch_store_unavailable or vouch_unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/agent/futures/account-state:
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: getAccountState
summary: Get Hyperliquid positions and risk state
description: 'Returns the agent''s current positions, margin summary, equity,
liquidation prices, and risk management state. Daily/weekly values are
conservative loss-pressure metrics (rolling closed PnL minus absolute
fill fees plus funding and negative current unrealized PnL only), not
full period returns.
Read-only lookup — no private key required.'
tags:
- Account
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/X-ClawHub-Skill'
- name: agentAddress
in: query
required: true
schema:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
description: Agent's EVM address (Hyperliquid API wallet)
responses:
'200':
description: Account state with risk info
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/AccountStateResponse'
'400':
$ref: '#/components/responses/BadRequest'
'402':
$ref: '#/components/responses/PaymentRequired'
components:
schemas:
DustStormWarning:
type: object
required:
- kind
- message
properties:
kind:
type: string
const: dust_storm
message:
type: string
RiskState:
type: object
properties:
dailyPnl:
type: string
dailyPnlPct:
type: string
weeklyPnl:
type: string
realizedDailyPnl:
type: string
realizedWeeklyPnl:
type: string
unrealizedPnl:
type: string
pnlSource:
type: string
enum:
- hyperliquid_venue_loss_pressure
pnlAsOf:
type: integer
format: int64
pnlMethodology:
type: string
drawdown:
type: string
peakEquity:
type: string
isTradingHalted:
type: boolean
haltReason:
type: string
nullable: true
isReducedSize:
type: boolean
openPositionCount:
type: integer
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
FuturesPosition:
type: object
properties:
coin:
type: string
size:
type: number
side:
type: string
enum:
- long
- short
entryPrice:
type: number
markPrice:
type: number
unrealizedPnl:
type: number
returnOnEquity:
type: number
leverage:
type: number
leverageType:
type: string
liquidationPrice:
type: number
nullable: true
marginUsed:
type: number
Guardrails:
type: object
properties:
maxLeverage:
type: integer
example: 5
maxRiskPerTrade:
type: string
example: 2%
maxPositions:
type: integer
dailyLossLimit:
type: string
example: -3%
weeklyLossLimit:
type: string
example: -7%
maxDrawdown:
type: string
example: -15%
AccountSummary:
type: object
properties:
equity:
type: string
totalNotionalPosition:
type: string
marginUsed:
type: string
availableMargin:
type: string
aggregateLeverage:
type: string
AccountStateResponse:
type: object
properties:
ok:
type: boolean
account:
$ref: '#/components/schemas/AccountSummary'
positions:
type: array
items:
$ref: '#/components/schemas/FuturesPosition'
risk:
$ref: '#/components/schemas/RiskState'
guardrails:
$ref: '#/components/schemas/Guardrails'
timestamp:
type: integer
warnings:
type: array
items:
$ref: '#/components/schemas/DustStormWarning'
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.'
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.
- 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)