---
title: "Create Swap"
method: POST
path: "/v1/swap"
tags: ["swap"]
---

# Create Swap

`POST /v1/swap`

## Request

- Base URL: `https://api.fereai.xyz`
- URL: `https://api.fereai.xyz/v1/swap`
- Auth: none declared

Execute a token swap.

Fully gasless — the user never needs the source chain's native
gas token. One unified call handles same-chain swaps, cross-chain
swaps, and EVM↔Solana bridges, with bridging built in.

Use ?wait=true&timeout=60 to block until the swap
completes instead of receiving a task_id.

Pass ``agent_id`` to trade from one of your own strategy wallets
instead of the main one. To sell a position, set ``token_out`` to
the chain's stablecoin. Selling the whole position (99.9% or more
of the balance) removes that coin's stop-loss/take-profit orders
automatically; a partial sell keeps them on the remaining amount.
``cancel_conditional_orders`` acts on ``token_out``'s orders, so it
does not clear the sold coin's orders.

## Query parameters

- `wait` boolean: Block until task completes
- `timeout` integer: Seconds to block when wait=true (max 90; the ~100s edge cuts longer waits — use wait=false + poll for longer).

## Request body

- SwapRequest
  - `agent_id` string, nullable: Optional: one of your own agents (e.g. a strategy wallet) to trade from. Defaults to your main agent. An agent you don't own returns 404.
  - `chain_id_in` integer, required: Source chain ID.
  - `chain_id_out` integer, required: Destination chain ID. Same as chain_id_in for same-chain swaps.
  - `token_in` string, required: Input token contract address.
  - `token_out` string, required: Output token contract address.
  - `amount` string, required: Amount in smallest unit (wei for EVM, lamports for Solana).
  - `slippage_bps` integer, nullable: Slippage tolerance in basis points (50 = 0.5%).
  - `dryrun` boolean: Simulate the swap without executing on-chain.
  - `stop_loss` HookConfig
    - `price_percentage` number, required: Price percentage trigger (e.g., 0.3 for -30% stop-loss, 1.0 for +100% take-profit).
    - `sell_percentage` number, required: Fraction of holdings to sell when triggered (0.0 to 1.0, where 1.0 = sell all).
  - `take_profit` HookConfig
    - `price_percentage` number, required: Price percentage trigger (e.g., 0.3 for -30% stop-loss, 1.0 for +100% take-profit).
    - `sell_percentage` number, required: Fraction of holdings to sell when triggered (0.0 to 1.0, where 1.0 = sell all).
  - `cancel_conditional_orders` boolean, nullable: Cancel existing stop-loss/take-profit orders for this token pair.

## Response `200`

Successful Response

- SwapResponse
  - `task_id` string, required: Celery task ID for the swap operation.
  - `status` string: Current task status.
  - `message` string: Human-readable status message.
  - `poll_url` string, nullable: Relative URL to poll for task status.
  - `result` unknown
  - `notification_stream` string: SSE stream URL for real-time updates.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/fereai/apis/fereai-gateway.md) - [All operations](https://skmtc.dev/fereai/apis/fereai-gateway/llms.txt) - [OpenAPI document](https://skmtc.dev/fereai/apis/fereai-gateway/revisions/ad211f8e2f30?raw)