curl -X POST "https://api.fibrous.finance/{network}/execute" \
-H "Content-Type: application/json" \
-d '{
"route": {
"success": true,
"inputToken": {
"name": "Wrapped Ether",
"address": "0x4200000000000000000000000000000000000006",
"decimals": 18,
"price": 3171.37
},
"outputToken": {
"name": "USD Coin",
"address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"decimals": 6,
"price": 0.99971
},
"inputAmount": "1000000000000000000",
"outputAmount": "3165007379",
"route": [...]
},
"slippage": 0.5,
"destination": "0x1234567890123456789012345678901234567890"
}'
const axios = require('axios');
const executeSwap = async () => {
const response = await axios.post(
'https://api.fibrous.finance/{network}/execute',
{
route: {
inputToken: {
address: '0x0000000000000000000000000000000000000000',
decimals: 18,
symbol: 'ETH'
},
outputToken: {
address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
decimals: 6,
symbol: 'USDC'
},
inputAmount: '1000000000000000000',
outputAmount: '2500000000'
},
slippage: 0.5,
destination: '0x1234567890123456789012345678901234567890'
},
{
headers: {
'Content-Type': 'application/json'
}
}
);
return response.data;
};
import requests
import json
url = "https://api.fibrous.finance/{network}/execute"
payload = {
"route": {
"inputToken": {
"address": "0x0000000000000000000000000000000000000000",
"decimals": 18,
"symbol": "ETH"
},
"outputToken": {
"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"decimals": 6,
"symbol": "USDC"
},
"inputAmount": "1000000000000000000",
"outputAmount": "2500000000"
},
"slippage": 0.5,
"destination": "0x1234567890123456789012345678901234567890"
}
headers = {
'Content-Type': 'application/json'
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.HashMap;
import java.util.Map;
public class FibrousExecute {
public static void main(String[] args) throws Exception {
String url = "https://api.fibrous.finance/{network}/execute";
Map<String, Object> route = new HashMap<>();
Map<String, Object> inputToken = new HashMap<>();
inputToken.put("address", "0x0000000000000000000000000000000000000000");
inputToken.put("decimals", 18);
inputToken.put("symbol", "ETH");
route.put("inputToken", inputToken);
Map<String, Object> outputToken = new HashMap<>();
outputToken.put("address", "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
outputToken.put("decimals", 6);
outputToken.put("symbol", "USDC");
route.put("outputToken", outputToken);
route.put("inputAmount", "1000000000000000000");
route.put("outputAmount", "2500000000");
Map<String, Object> payload = new HashMap<>();
payload.put("route", route);
payload.put("slippage", 0.5);
payload.put("destination", "0x1234567890123456789012345678901234567890");
ObjectMapper mapper = new ObjectMapper();
String jsonBody = mapper.writeValueAsString(payload);
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(jsonBody))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Response: " + response.body());
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
type Route struct {
InputToken map[string]interface{} `json:"inputToken"`
OutputToken map[string]interface{} `json:"outputToken"`
InputAmount string `json:"inputAmount"`
OutputAmount string `json:"outputAmount"`
}
type Payload struct {
Route Route `json:"route"`
Slippage float64 `json:"slippage"`
Destination string `json:"destination"`
}
func main() {
url := "https://api.fibrous.finance/{network}/execute"
route := Route{
InputToken: map[string]interface{}{
"address": "0x0000000000000000000000000000000000000000",
"decimals": 18,
"symbol": "ETH",
},
OutputToken: map[string]interface{}{
"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"decimals": 6,
"symbol": "USDC",
},
InputAmount: "1000000000000000000",
OutputAmount: "2500000000",
}
payload := Payload{
Route: route,
Slippage: 0.5,
Destination: "0x1234567890123456789012345678901234567890",
}
jsonData, err := json.Marshal(payload)
if err != nil {
panic(err)
}
req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println("Response:", string(body))
}
{
"route": {
"amount_in": "1000000000000000000",
"amount_out": "3165007379",
"min_received": "3149182360",
"destination": "0x1234567890123456789012345678901234567890",
"swap_type": 0
},
"swap_parameters": [
{
"token_in": "0x4200000000000000000000000000000000000006",
"token_out": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"rate": "3165007379",
"protocol_id": "9",
"pool_address": "0x72ab388e2e2f6facef59e3c3fa2c4e29011c2d38",
"swap_type": 0,
"extra_data": "0x0064"
}
],
"calldata": "0x...",
"to": "0x274602a953847d807231d2370072f5f4e4594b44",
"value": "1000000000000000000"
}
Core Endpoints
Execute Swap
Execute a token swap using the optimal route
POST
/
{network}
/
execute
curl -X POST "https://api.fibrous.finance/{network}/execute" \
-H "Content-Type: application/json" \
-d '{
"route": {
"success": true,
"inputToken": {
"name": "Wrapped Ether",
"address": "0x4200000000000000000000000000000000000006",
"decimals": 18,
"price": 3171.37
},
"outputToken": {
"name": "USD Coin",
"address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"decimals": 6,
"price": 0.99971
},
"inputAmount": "1000000000000000000",
"outputAmount": "3165007379",
"route": [...]
},
"slippage": 0.5,
"destination": "0x1234567890123456789012345678901234567890"
}'
const axios = require('axios');
const executeSwap = async () => {
const response = await axios.post(
'https://api.fibrous.finance/{network}/execute',
{
route: {
inputToken: {
address: '0x0000000000000000000000000000000000000000',
decimals: 18,
symbol: 'ETH'
},
outputToken: {
address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
decimals: 6,
symbol: 'USDC'
},
inputAmount: '1000000000000000000',
outputAmount: '2500000000'
},
slippage: 0.5,
destination: '0x1234567890123456789012345678901234567890'
},
{
headers: {
'Content-Type': 'application/json'
}
}
);
return response.data;
};
import requests
import json
url = "https://api.fibrous.finance/{network}/execute"
payload = {
"route": {
"inputToken": {
"address": "0x0000000000000000000000000000000000000000",
"decimals": 18,
"symbol": "ETH"
},
"outputToken": {
"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"decimals": 6,
"symbol": "USDC"
},
"inputAmount": "1000000000000000000",
"outputAmount": "2500000000"
},
"slippage": 0.5,
"destination": "0x1234567890123456789012345678901234567890"
}
headers = {
'Content-Type': 'application/json'
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.HashMap;
import java.util.Map;
public class FibrousExecute {
public static void main(String[] args) throws Exception {
String url = "https://api.fibrous.finance/{network}/execute";
Map<String, Object> route = new HashMap<>();
Map<String, Object> inputToken = new HashMap<>();
inputToken.put("address", "0x0000000000000000000000000000000000000000");
inputToken.put("decimals", 18);
inputToken.put("symbol", "ETH");
route.put("inputToken", inputToken);
Map<String, Object> outputToken = new HashMap<>();
outputToken.put("address", "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
outputToken.put("decimals", 6);
outputToken.put("symbol", "USDC");
route.put("outputToken", outputToken);
route.put("inputAmount", "1000000000000000000");
route.put("outputAmount", "2500000000");
Map<String, Object> payload = new HashMap<>();
payload.put("route", route);
payload.put("slippage", 0.5);
payload.put("destination", "0x1234567890123456789012345678901234567890");
ObjectMapper mapper = new ObjectMapper();
String jsonBody = mapper.writeValueAsString(payload);
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(jsonBody))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Response: " + response.body());
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
type Route struct {
InputToken map[string]interface{} `json:"inputToken"`
OutputToken map[string]interface{} `json:"outputToken"`
InputAmount string `json:"inputAmount"`
OutputAmount string `json:"outputAmount"`
}
type Payload struct {
Route Route `json:"route"`
Slippage float64 `json:"slippage"`
Destination string `json:"destination"`
}
func main() {
url := "https://api.fibrous.finance/{network}/execute"
route := Route{
InputToken: map[string]interface{}{
"address": "0x0000000000000000000000000000000000000000",
"decimals": 18,
"symbol": "ETH",
},
OutputToken: map[string]interface{}{
"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"decimals": 6,
"symbol": "USDC",
},
InputAmount: "1000000000000000000",
OutputAmount: "2500000000",
}
payload := Payload{
Route: route,
Slippage: 0.5,
Destination: "0x1234567890123456789012345678901234567890",
}
jsonData, err := json.Marshal(payload)
if err != nil {
panic(err)
}
req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println("Response:", string(body))
}
{
"route": {
"amount_in": "1000000000000000000",
"amount_out": "3165007379",
"min_received": "3149182360",
"destination": "0x1234567890123456789012345678901234567890",
"swap_type": 0
},
"swap_parameters": [
{
"token_in": "0x4200000000000000000000000000000000000006",
"token_out": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"rate": "3165007379",
"protocol_id": "9",
"pool_address": "0x72ab388e2e2f6facef59e3c3fa2c4e29011c2d38",
"swap_type": 0,
"extra_data": "0x0064"
}
],
"calldata": "0x...",
"to": "0x274602a953847d807231d2370072f5f4e4594b44",
"value": "1000000000000000000"
}
Overview
V2 Available: This endpoint maps to
/{network}/v2/calldata in V2, with integrator support and metadata. See Calldata V2 and the V2 Migration Guide.Supported Networks
- Base
- HyperEVM
- Citrea
- Monad
- Starknet
https://api.fibrous.finance/base/execute
https://api.fibrous.finance/hyperevm/execute
https://api.fibrous.finance/citrea/execute
https://api.fibrous.finance/monad/execute
https://api.fibrous.finance/starknet/execute
Starknet execution uses Cairo-specific transaction format. See Starknet API for details.
Request Body Parameters
RouteResponse
required
The route object returned from the
/route endpoint. This contains all necessary information about the swap path and expected outcomes.number
default:"0.5"
required
Maximum acceptable slippage in percentage (0.1 to 100).Example:
0.5 for 0.5% slippage tolerancestring
required
The destination address to receive the output tokens.
number
Unix timestamp (in seconds) after which the transaction will revert.Defaults to 20 minutes from the current time if not specified.
Response
object
object[]
Swap parameters for every hop in the route
string
The encoded transaction calldata ready for execution
string
Fibrous Router contract address to send the transaction to
string
The amount of native token to send with the transaction (for native token swaps)
Example Request
curl -X POST "https://api.fibrous.finance/{network}/execute" \
-H "Content-Type: application/json" \
-d '{
"route": {
"success": true,
"inputToken": {
"name": "Wrapped Ether",
"address": "0x4200000000000000000000000000000000000006",
"decimals": 18,
"price": 3171.37
},
"outputToken": {
"name": "USD Coin",
"address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"decimals": 6,
"price": 0.99971
},
"inputAmount": "1000000000000000000",
"outputAmount": "3165007379",
"route": [...]
},
"slippage": 0.5,
"destination": "0x1234567890123456789012345678901234567890"
}'
const axios = require('axios');
const executeSwap = async () => {
const response = await axios.post(
'https://api.fibrous.finance/{network}/execute',
{
route: {
inputToken: {
address: '0x0000000000000000000000000000000000000000',
decimals: 18,
symbol: 'ETH'
},
outputToken: {
address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
decimals: 6,
symbol: 'USDC'
},
inputAmount: '1000000000000000000',
outputAmount: '2500000000'
},
slippage: 0.5,
destination: '0x1234567890123456789012345678901234567890'
},
{
headers: {
'Content-Type': 'application/json'
}
}
);
return response.data;
};
import requests
import json
url = "https://api.fibrous.finance/{network}/execute"
payload = {
"route": {
"inputToken": {
"address": "0x0000000000000000000000000000000000000000",
"decimals": 18,
"symbol": "ETH"
},
"outputToken": {
"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"decimals": 6,
"symbol": "USDC"
},
"inputAmount": "1000000000000000000",
"outputAmount": "2500000000"
},
"slippage": 0.5,
"destination": "0x1234567890123456789012345678901234567890"
}
headers = {
'Content-Type': 'application/json'
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.HashMap;
import java.util.Map;
public class FibrousExecute {
public static void main(String[] args) throws Exception {
String url = "https://api.fibrous.finance/{network}/execute";
Map<String, Object> route = new HashMap<>();
Map<String, Object> inputToken = new HashMap<>();
inputToken.put("address", "0x0000000000000000000000000000000000000000");
inputToken.put("decimals", 18);
inputToken.put("symbol", "ETH");
route.put("inputToken", inputToken);
Map<String, Object> outputToken = new HashMap<>();
outputToken.put("address", "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
outputToken.put("decimals", 6);
outputToken.put("symbol", "USDC");
route.put("outputToken", outputToken);
route.put("inputAmount", "1000000000000000000");
route.put("outputAmount", "2500000000");
Map<String, Object> payload = new HashMap<>();
payload.put("route", route);
payload.put("slippage", 0.5);
payload.put("destination", "0x1234567890123456789012345678901234567890");
ObjectMapper mapper = new ObjectMapper();
String jsonBody = mapper.writeValueAsString(payload);
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(jsonBody))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Response: " + response.body());
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
type Route struct {
InputToken map[string]interface{} `json:"inputToken"`
OutputToken map[string]interface{} `json:"outputToken"`
InputAmount string `json:"inputAmount"`
OutputAmount string `json:"outputAmount"`
}
type Payload struct {
Route Route `json:"route"`
Slippage float64 `json:"slippage"`
Destination string `json:"destination"`
}
func main() {
url := "https://api.fibrous.finance/{network}/execute"
route := Route{
InputToken: map[string]interface{}{
"address": "0x0000000000000000000000000000000000000000",
"decimals": 18,
"symbol": "ETH",
},
OutputToken: map[string]interface{}{
"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"decimals": 6,
"symbol": "USDC",
},
InputAmount: "1000000000000000000",
OutputAmount: "2500000000",
}
payload := Payload{
Route: route,
Slippage: 0.5,
Destination: "0x1234567890123456789012345678901234567890",
}
jsonData, err := json.Marshal(payload)
if err != nil {
panic(err)
}
req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println("Response:", string(body))
}
{
"route": {
"amount_in": "1000000000000000000",
"amount_out": "3165007379",
"min_received": "3149182360",
"destination": "0x1234567890123456789012345678901234567890",
"swap_type": 0
},
"swap_parameters": [
{
"token_in": "0x4200000000000000000000000000000000000006",
"token_out": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"rate": "3165007379",
"protocol_id": "9",
"pool_address": "0x72ab388e2e2f6facef59e3c3fa2c4e29011c2d38",
"swap_type": 0,
"extra_data": "0x0064"
}
],
"calldata": "0x...",
"to": "0x274602a953847d807231d2370072f5f4e4594b44",
"value": "1000000000000000000"
}
Best Practices
-
Route Freshness
- Always use a fresh route from the
/routeendpoint - Routes can become stale due to market movements
- Implement retry logic with fresh routes if execution fails
- Always use a fresh route from the
-
Slippage Management
- Set appropriate slippage tolerance based on:
- Token pair volatility
- Available liquidity
- Market conditions
- Higher values increase success rate but may result in worse prices
- Lower values ensure better prices but may cause more failed transactions
- Set appropriate slippage tolerance based on:
-
Deadline Setting
- Set reasonable deadlines to prevent stale transactions
- Consider network congestion when setting deadlines
- Default of 20 minutes is suitable for most cases
-
Gas Optimization
- Monitor gas costs in responses to optimize future transactions
- Consider using direct routes for major pairs
- Batch multiple swaps when possible
Error Responses
Route Expired
Route Expired
Status Code: 400Solution: Fetch a new route and retry the execution.
{
"error": "Route expired",
"message": "The provided route is no longer valid. Please fetch a new route."
}
Insufficient Liquidity
Insufficient Liquidity
Status Code: 400Solution: Reduce the swap amount or try again later.
{
"error": "Insufficient liquidity",
"message": "Not enough liquidity available for this swap amount."
}
Invalid Slippage
Invalid Slippage
Status Code: 400Solution: Adjust slippage to be within the valid range.
{
"error": "Invalid slippage",
"message": "Slippage must be between 0.1 and 100"
}
Network-Specific Notes
- EVM Chains (Base, HyperEVM, Citrea)
- Starknet
- Use standard EVM transaction format
- Native token swaps require sending value with transaction
- Approve token spending before swap if not native token
- Gas estimation included in response
- Uses Cairo-specific transaction format
- Different approval mechanism
- See Starknet Execute for details
Complete Swap Flow
Related Endpoints
- Get Route - Find optimal route before execution
- Get Calldata - Alternative endpoint combining route and execute
- Health Check - Check API status
- Calldata V2 - V2 equivalent of this endpoint
- V2 Migration Guide - Migrate to V2 API
⌘I