---
title: "Create an execution intent with a firm single-provider quote"
method: POST
path: "/v1/agent/quote-intent"
tags: ["Swap"]
---

# Create an execution intent with a firm single-provider quote

`POST /v1/agent/quote-intent`

## Request

- Base URL: `https://www.farmdash.one/api`
- URL: `https://www.farmdash.one/api/v1/agent/quote-intent`
- Auth: none declared

Explicit execution intent. Requires exact chain pair, token pair,
amount, real wallet/taker, destination, slippage, and a client
idempotency key; the fee tier is resolved server-side before any
provider call. One intent contacts exactly one primary provider; a
sequential alternate follows only a genuine primary failure.
Identical intents reuse the stored firm quote (HTTP 200 reused:true);
changed parameters never reuse a stale quote. The firm quote flows
through simulate, approval, and prepare without further provider
quote requests. Quote is not execution; FarmDash never signs or
broadcasts.
Provider prerequisites (compatibility swaps):
A firm quote reports readiness plus any provider prerequisite that must be
satisfied before simulation. A prerequisite recipe is NOT an executable swap
transaction and must never be passed directly into simulation.

LI.FI: when approval.required is true, approval.spender is the spender
FarmDash observed. FarmDash does not build or broadcast the ERC-20 approval
transaction: the customer-controlled wallet must satisfy the ERC-20 allowance
locally (standard approve(spender, amount)), wait for that transaction to
confirm, then request a FRESH firm quote so FarmDash re-checks the wallet
balance and allowance. Proceed only when executionReady is true. The zero
address 0x0000000000000000000000000000000000000000 is the LI.FI native-token
sentinel and requires no ERC-20 allowance; it is not WETH.

Relay: providerExecutionPlan is an ORDERED recipe whose steps have kind
approve, transaction, signature or unknown, and carry status, to, data,
value and chainId; approve steps also carry approvalSpender and
approvalAmount, and signature steps carry signatureKind with sign/post/check.
Follow planContinuation: "re_quote_after_approval" means complete the
approval locally then obtain a fresh quote;
"execute_provider_plan_and_check" means execute the ordered sign/post/check
recipe exactly as returned; "provider_recipe_unsupported" means stop and do
not treat the recipe as executable. A required step of kind unknown remains
blocking. Never flatten a multi-step recipe into its first transaction.
When a value is unreadable FarmDash reports unknown rather than assuming the
prerequisite is satisfied. Prerequisite completion is not settlement.

## Request body

- object
  - `fromChainId` integer, required
  - `toChainId` integer, required
  - `fromToken` string, required
  - `toToken` string, required
  - `fromAmount` string, required
  - `walletAddress` string, required
  - `toAddress` string, required
  - `slippage` number, required
  - `protocol` 'lifi' | 'relay'
  - `idempotencyKey` string, required
  - `continuationId` string, uuid: Optional context correlation only; all existing admission and wallet authority requirements remain unchanged.
  - `executionTrialProof` ExecutionTrialProof: Locally signed server-issued commercial identity challenge. Creates no transaction authority or delegation. Valid for five minutes. Never send private keys.
    - `issuedAt` integer, required
    - `signature` string, required
  - `executionMode` 'USER_SIGNED' | 'BOUNDED_AUTONOMOUS'
  - `sessionId` string
  - `grantId` string
  - `sessionToken` string

## Response `200`

Stored firm quote reused for an identical intent

- FirmQuoteResponse
  - `intentId` string, required
  - `quoteKind` 'firm_quote', required
  - `reused` boolean, required
  - `marketBenchmark` object, nullable
  - `selectedProvider` 'lifi' | 'relay', required: Swap quote provider. Automatic routing compares all healthy compatible providers (LI.FI, Relay; 0x paused until reinstated); force one with ?protocol= (deterministic, never silent fallback).
  - `firmQuote` object, required
  - `expiresAt` string, required
  - `executionReady` boolean, required
  - `approval` object, nullable
  - `simulationRequirements` object, required
    - `required` boolean
    - `simulate_url` string
    - `intent_id` string: fd_intent_* execution-simulation identity. Pass this value to /v1/simulate.
    - `valid_for_execution` boolean
    - `plan` object, nullable
    - `signatures` unknown[], nullable
      - unknown
  - `attempts` object[], required
  - `alternateUsed` boolean, required
  - `unsigned` true, required
  - `broadcast_by_farmdash` false, required
  - `executionAlpha` ExecutionAlphaReport, required
    - `selectedProtocol` 'lifi' | 'relay': Swap quote provider. Automatic routing compares all healthy compatible providers (LI.FI, Relay; 0x paused until reinstated); force one with ?protocol= (deterministic, never silent fallback).
    - `routeReason` string
    - `mevProtection` object
      - `safetyMode` 'strict' | 'balanced'
      - `actualSlippageBps` integer
      - `maxRecommendedSlippageBps` integer
    - `candidates` RouteCandidate[]
      - `protocol` 'lifi' | 'relay': Swap quote provider. Automatic routing compares all healthy compatible providers (LI.FI, Relay; 0x paused until reinstated); force one with ?protocol= (deterministic, never silent fallback).
      - `estimatedOutput` string
      - `feeAmountUsd` number
      - `gasEstimateUsd` number, nullable
      - `bridgeFeeUsd` number, nullable
      - `routeRiskScore` number
      - `selected` boolean
    - `quoteDecay` QuoteDecayMetrics
      - `previousObservedAt` integer, nullable
      - `quoteAgeMs` integer, nullable
      - `outputDecayBps` number
      - `gasIncreaseBps` number
      - `severity` 'none' | 'low' | 'medium' | 'high'
    - `netEdge` NetEdgeAnalysis
      - `expectedUpsideUsd` number, nullable
      - `protocolFeeUsd` number
      - `gasUsd` number
      - `bridgeFeeUsd` number
      - `riskBufferUsd` number
      - `totalCostUsd` number
      - `netEdgeUsd` number, nullable
      - `positive` boolean, nullable
      - `enforced` boolean
  - `riskReport` SwapRiskReport, required
    - `flags` RiskFlag[]
      - `code` string, required
      - `category` 'approval' | 'bridge' | 'contract' | 'token' | 'health' | 'execution', required
      - `severity` 'low' | 'medium' | 'high' | 'critical', required
      - `title` string, required
      - `message` string, required
      - `metadata` object
    - `approval` AllowanceStatus
      - `spender` string, nullable
      - `allowance` string, nullable
      - `requiredAmount` string
      - `approvalNeeded` boolean
      - `overApproved` boolean
      - `source` 'onchain' | 'quote_fallback' | 'unavailable'
    - `pegChecks` PegCheck[]
      - `tokenAddress` string
      - `symbol` string
      - `reference` 'USD' | 'ETH'
      - `priceUsd` number, nullable
      - `referencePriceUsd` number, nullable
      - `deviationPct` number, nullable
      - `alert` boolean
    - `health` HealthCheck
      - `healthFactor` number, nullable
      - `liquidationBufferPct` number, nullable
      - `alertLevel` 'none' | 'warning' | 'critical'
      - `shouldHalt` boolean
    - `shouldHalt` boolean
    - `haltReasons` string[]
  - `execution_boundary` object, required
    - `state` string
    - `simulation_required` boolean
    - `local_signature_required` boolean
    - `farmdash_broadcasts_transaction` boolean
  - `note` string, required

## Other responses

- `201`: Firm quote bound to a new execution intent
- `400`: Invalid parameters
- `402`: Free-tier limit exceeded — x402 payment required
- `409`: This idempotencyKey was already used for a materially different request (idempotency_conflict). Generate a new key for a new logical swap; retrying the same key never merges them.
- `413`: Request body too large. Execution-facing bodies are capped at 32 KB.
- `429`: Rate limit exceeded
- `502`: Typed live quote provider degradation

---

[API](https://skmtc.dev/farmdash/apis/farmdash-agent-api.md) · [All operations](https://skmtc.dev/farmdash/apis/farmdash-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/farmdash/apis/farmdash-agent-api/revisions/96310281f58c?raw)