---
title: "Prepare a signed compatibility-swap transaction"
method: POST
path: "/agents/swap"
tags: ["Swap"]
---

# Prepare a signed compatibility-swap transaction

`POST /agents/swap`

## Request

- Base URL: `https://www.farmdash.one/api`
- URL: `https://www.farmdash.one/api/agents/swap`
- Auth: one of:
  - HTTP bearer
  - none

Compatibility transaction-preparation endpoint. It requires a fresh successful
`simulationId`, authenticates the customer wallet with EIP-191, validates the released
provider boundary, and returns the exact prepared transaction payload.

FarmDash does not broadcast the returned compatibility-swap transaction. The customer
wallet signs and submits the transaction directly to the target network. The chosen
aggregator or router protocol (automatic multi-provider routing:
same-chain LI.FI + Relay; cross-chain LI.FI + Relay; 0x is operator-paused
until reinstated and is never primary or fallback)
executes the swap.

**Signature canonicalization**: construct
`v1:FARMDASH_SWAP:{fromChainId}:{toChainId}:{fromToken}:{toToken}:{fromAmount}:{agentAddress}:{toAddress}:{nonce}`
after lowercasing every `0x`-prefixed field, including token addresses. Sign the exact
UTF-8 string with EIP-191/personal_sign. A 428 simulation-gate response is evaluated before
signature verification and does not prove the signature is valid.

For LI.FI native ETH routes use the zero-address native-token sentinel, not the WETH contract.

**Fee schedule** (combined routing target; LI.FI 25 bps platform component deducted, not stacked; gas/slippage excluded): 50 bps under $10k, 45 bps at $10k+, 40 bps at $100k+, 30 bps at $1M+.

## Headers

- `X-ClawHub-Skill` string

## Request body

- SwapRequest
  - `fromChainId` 1 | 10 | 137 | 8453 | 42161 | 59144, required
  - `toChainId` 1 | 10 | 137 | 8453 | 42161 | 59144, required
  - `fromToken` string, required
  - `toToken` string, required
  - `fromAmount` string, required: Amount in wei
  - `agentAddress` string, required: Agent wallet address (signer)
  - `toAddress` string, required: Destination wallet for swapped tokens
  - `slippage` number: Slippage tolerance in percent (capped at 5%)
  - `protocol` 'lifi' | 'relay'
  - `volumeHintUSD` number: Advisory telemetry only — never determines the fee tier. Fee BPS uses server-oracle-derived input volume exclusively (50 bps under $10k, 45 bps at $10k+, 40 bps at $100k+, 30 bps at $1M+ combined routing target); unknown volume pays the default tier.
  - `expectedUpsideUsd` number: Optional upside estimate in USD for positive-net-edge checks
  - `riskBufferUsd` number: Optional extra execution-risk buffer in USD
  - `healthFactor` number: Optional lending health factor supplied by the caller
  - `liquidationBufferPct` number: Optional liquidation-buffer percentage supplied by the caller
  - `walletAddress` string: Optional wallet address used for on-chain approval checks
  - `safetyMode` 'strict' | 'balanced'
  - `simulationId` string, required: Fresh successful simulation_id from POST /v1/simulate
  - `intentId` string: Optional qi_* quote-cache/idempotency identity; must match the simulation when supplied. Do not pass this value to /v1/simulate.
  - `nonce` string, required: Current timestamp in milliseconds (60s window)
  - `signature` string, required: EIP-191 personal_sign of the v1 versioned payload

## Response `200`

Executable swap with transaction calldata

- SwapResult
  - `protocol` '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).
  - `estimatedOutput` string, required
  - `feeBps` integer, required
  - `feeAmountUSD` string, required
  - `feeEventId` string, uuid: Use with /agents/confirm to confirm settlement
  - `gasEstimate` string, required
  - `txData` SwapTxData, required
    - `to` string, required: Protocol contract address (NOT FarmDash)
    - `data` string, required: Encoded calldata
    - `value` string, required: Native token value in wei
    - `chainId` integer, required
  - `expiresAt` integer, required
  - `allowanceTarget` string, nullable
  - `gasEstimateUsd` number, nullable
  - `bridgeFeeUsd` number, nullable
  - `simulation` object
  - `executionAlpha` ExecutionAlphaReport
    - `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
    - `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[]
  - `confirmUrl` string

## Other responses

- `400`: Invalid parameters
- `401`: Invalid signature or expired nonce
- `402`: Free-tier limit exceeded — x402 payment required
- `409`: Swap halted by Risk Sentinel guardrails
- `428`: Missing, expired, failed, or mismatched preflight simulation
- `429`: Rate limit exceeded

---

[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)