V2 API Migration Guide

Overview

Fibrous Router API V2 introduces enhanced features and improved response structure while maintaining backward compatibility with V1 endpoints. This guide will help you migrate your integration to take advantage of V2 features.

Quick Reference: Endpoint Mapping

Important: V2 endpoint names have changed to better reflect their functionality. Pay special attention to these mappings:

V1 Endpoint	V2 Endpoint	HTTP Method	What Changed
`/{network}/route`	`/{network}/v2/route`	GET	Same functionality, added integrator support
`/{network}/calldata`	`/{network}/v2/routeAndCalldata`	GET	Renamed - Same functionality (route + calldata in one call)
`/{network}/execute`	`/{network}/v2/calldata`	POST	Renamed - Same functionality (generate calldata from route)
`/{network}/healthcheck`	`/{network}/v2/healthcheck`	GET	Same functionality, added meta field

Key Changes:

V1 /calldata → V2 /routeAndCalldata: Endpoint renamed for clarity (still GET, still returns route + calldata)
V1 /execute → V2 /calldata: Endpoint renamed for clarity (still POST, still generates calldata from route)

What’s New in V2

Integrator Features

Support for integrator fees and surplus sharing to monetize your integration

Enhanced Metadata

All responses include API version and timestamp for better tracking

Endpoint Reorganization

Endpoints renamed for clarity: /calldata → /routeAndCalldata, /execute → /calldata

Improved Structure

Better organized response format with consistent meta fields

Key Differences

Response Structure

V1 Response:

{
  "success": true,
  "inputToken": {...},
  "outputToken": {...},
  "outputAmount": "1000000000"
}

V2 Response:

{
  "success": true,
  "inputToken": {...},
  "outputToken": {...},
  "outputAmount": "1000000000",
  "outputAmountAfterFee": "995000000",
  "meta": {
    "apiVersion": "2.0",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Endpoint Mapping

V2 API reorganizes endpoint names for better clarity. Here’s how V2 endpoints map to V1:

V1 Endpoint	V2 Endpoint	Description	HTTP Method
`/{network}/route`	`/{network}/v2/route`	Find optimal route	GET
`/{network}/calldata`	`/{network}/v2/routeAndCalldata`	Get route and calldata in one request	GET
`/{network}/execute`	`/{network}/v2/calldata`	Generate calldata from existing route	POST
`/{network}/healthcheck`	`/{network}/v2/healthcheck`	Health check	GET

Important: The V2 endpoint names better reflect their functionality:

routeAndCalldata (V2) replaces calldata (V1) - combines route finding and calldata generation
calldata (V2) replaces execute (V1) - generates calldata from a pre-calculated route

Integrator Features

V2 supports monetization through integrator fees or surplus sharing:

Integrator Fee: Charge a percentage (0-5%) on swaps routed through your integration
Integrator Surplus: Share in surplus value (0-50%) when routing finds better prices
Note: You cannot use both fee and surplus in the same request

API Key Required: Integrator features require an API key from Fibrous. Generate and manage your API keys at the Fibrous Partnership Portal.

Migration Steps

Step 1: Update Base URL

Change your base URL from:

https://api.fibrous.finance/{network}

To:

https://api.fibrous.finance/{network}/v2

Step 2: Handle Meta Field

All V2 responses include a meta field. Update your response handling:

// V1
const { success, outputAmount } = response;

// V2
const { success, outputAmount, meta } = response;
console.log(`API Version: ${meta.apiVersion}`);
console.log(`Response Time: ${meta.timestamp}`);

Step 3: Update Route Endpoint

V1:

GET /{network}/route?amount=1000&tokenInAddress=0x...&tokenOutAddress=0x...

V2:

GET /{network}/v2/route?amount=1000&tokenInAddress=0x...&tokenOutAddress=0x...

Optional integrator parameters:

GET /{network}/v2/route?amount=1000&tokenInAddress=0x...&tokenOutAddress=0x...&integratorAddress=0x...&integratorFeePercentageBps=100

Step 4: Update Calldata Endpoint (V1 → routeAndCalldata V2)

Important: V1’s /calldata endpoint is now /routeAndCalldata in V2. V1 /calldata endpoint:

// V1: GET request with query parameters
GET /{network}/calldata?amount=1000&tokenInAddress=0x...&tokenOutAddress=0x...&slippage=0.5&destination=0x...

V2 /routeAndCalldata endpoint:

// V2: Same functionality, renamed for clarity
GET /{network}/v2/routeAndCalldata?amount=1000&tokenInAddress=0x...&tokenOutAddress=0x...&slippage=0.5&destination=0x...

// Response includes both route and calldata
const { route, calldata, router_address, meta } = await response.json();

Migration Note: If you were using V1’s /calldata endpoint, update your code to use /v2/routeAndCalldata. The functionality is the same - it gets route and calldata in one request.

Step 5: Update Execute Endpoint (V1 → calldata V2)

Important: V1’s /execute endpoint is now /calldata in V2. V1 /execute endpoint:

// V1: POST request with route object
POST /{network}/execute
Body: {
  "route": {...},
  "slippage": 0.5,
  "destination": "0x..."
}

V2 /calldata endpoint:

// V2: Same functionality, renamed for clarity
POST /{network}/v2/calldata
Body: {
  "route": {...},
  "slippage": 0.5,
  "destination": "0x...",
  "integratorAddress": "0x...", // optional
  "integratorFeePercentageBps": 100 // optional
}

Migration Note: If you were using V1’s /execute endpoint, update your code to use /v2/calldata. The functionality is the same - it generates calldata from a pre-calculated route.

Step 6: Handle Integrator Features (Optional)

API Key Required: To use integrator features, you must first obtain an API key from Fibrous. Generate and manage your API keys at the Fibrous Partnership Portal.

If you want to monetize your integration:

// Set up API key authentication
const headers = {
  'X-API-Key': 'your-api-key-here'
};

// Use integrator fee
const response = await fetch('/{network}/v2/route', {
  headers,
  params: {
    amount: '1000',
    tokenInAddress: '0x...',
    tokenOutAddress: '0x...',
    integratorAddress: '0xYourWallet',
    integratorFeePercentageBps: 100 // 1% fee
  }
});

// Response includes outputAmountAfterFee
const { outputAmount, outputAmountAfterFee, integratorFeePercentageBps } = response;

Parameter Changes

New Optional Parameters

All V2 endpoints support these optional integrator parameters:

Parameter	Type	Description
`integratorAddress`	string	Wallet address to receive fees/surplus
`integratorFeePercentageBps`	number	Fee percentage in basis points (0-500, max 5%)
`integratorSurplusPercentageBps`	number	Surplus percentage in basis points (0-5000, max 50%)

API Key Required: Integrator parameters require an API key from Fibrous. Generate and manage your API keys at the Fibrous Partnership Portal.You cannot use both integratorFeePercentageBps and integratorSurplusPercentageBps in the same request.

Response Field Changes

Field	V1	V2	Notes
`meta`	❌	✅	Always present in V2
`outputAmountAfterFee`	❌	✅	Present when integrator fee is used
`integratorAddress`	❌	✅	Present when integrator features are used
`integratorFeePercentageBps`	❌	✅	Present when integrator fee is set
`integratorSurplusPercentageBps`	❌	✅	Present when integrator surplus is set
`integratorName`	❌	✅	Present when API key is used

Code Examples

Complete Migration Example

// V1 Implementation
async function swapV1(amount, tokenIn, tokenOut, slippage, destination) {
  // Step 1: Get route
  const routeResponse = await fetch(
    `https://api.fibrous.finance/{network}/route?amount=${amount}&tokenInAddress=${tokenIn}&tokenOutAddress=${tokenOut}`
  );
  const route = await routeResponse.json();
  
  // Step 2: Get calldata (V1 endpoint name)
  const calldataResponse = await fetch(
    `https://api.fibrous.finance/{network}/calldata?amount=${amount}&tokenInAddress=${tokenIn}&tokenOutAddress=${tokenOut}&slippage=${slippage}&destination=${destination}`
  );
  const calldata = await calldataResponse.json();
  
  return { route, calldata };
}

// V2 Implementation - Option 1: Using routeAndCalldata (replaces V1 calldata)
async function swapV2_Option1(amount, tokenIn, tokenOut, slippage, destination, apiKey = null) {
  const headers = apiKey ? { 'X-API-Key': apiKey } : {};
  
  // Single call to get route and calldata (V1's /calldata → V2's /routeAndCalldata)
  const response = await fetch(
    `https://api.fibrous.finance/{network}/v2/routeAndCalldata?amount=${amount}&tokenInAddress=${tokenIn}&tokenOutAddress=${tokenOut}&slippage=${slippage}&destination=${destination}`,
    { headers }
  );
  
  const data = await response.json();
  
  // Log API version for debugging
  console.log(`Using API ${data.meta.apiVersion} at ${data.meta.timestamp}`);
  
  return {
    route: data.route,
    calldata: data.calldata,
    routerAddress: data.router_address,
    meta: data.meta
  };
}

// V2 Implementation - Option 2: Using route + calldata (replaces V1 execute)
async function swapV2_Option2(amount, tokenIn, tokenOut, slippage, destination, apiKey = null) {
  const headers = apiKey ? { 'X-API-Key': apiKey } : {};
  
  // Step 1: Get route
  const routeResponse = await fetch(
    `https://api.fibrous.finance/{network}/v2/route?amount=${amount}&tokenInAddress=${tokenIn}&tokenOutAddress=${tokenOut}`,
    { headers }
  );
  const route = await routeResponse.json();
  
  // Step 2: Generate calldata from route (V1's /execute → V2's /calldata)
  const calldataResponse = await fetch(
    `https://api.fibrous.finance/{network}/v2/calldata`,
    {
      method: 'POST',
      headers: {
        ...headers,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        route,
        slippage,
        destination
      })
    }
  );
  const calldata = await calldataResponse.json();
  
  return {
    route,
    calldata,
    meta: calldata.meta
  };
}

With Integrator Features

async function swapWithIntegratorFee(amount, tokenIn, tokenOut, slippage, destination, apiKey, integratorAddress) {
  const headers = { 'X-API-Key': apiKey };
  
  const params = new URLSearchParams({
    amount,
    tokenInAddress: tokenIn,
    tokenOutAddress: tokenOut,
    slippage,
    destination,
    integratorAddress,
    integratorFeePercentageBps: '100' // 1% fee
  });
  
  const response = await fetch(
    `https://api.fibrous.finance/{network}/v2/route?${params}`,
    { headers }
  );
  
  const data = await response.json();
  
  // Show user the amount after fee
  const amountAfterFee = data.outputAmountAfterFee;
  const feeAmount = BigInt(data.outputAmount) - BigInt(amountAfterFee);
  
  console.log(`Output: ${data.outputAmount}`);
  console.log(`After ${data.integratorFeePercentageBps / 100}% fee: ${amountAfterFee}`);
  console.log(`Fee earned: ${feeAmount}`);
  
  return data;
}

Backward Compatibility

V1 endpoints remain available and fully functional. You can migrate at your own pace without breaking existing integrations.

V1 endpoints: https://api.fibrous.finance/{network}/*
V2 endpoints: https://api.fibrous.finance/{network}/v2/*

Both versions will continue to be supported, but we recommend migrating to V2 to take advantage of new features.

Testing Your Migration

Test with small amounts first
- Verify responses match expected format
- Check that meta fields are present
- Validate integrator features if used
Monitor API version in responses
- Log meta.apiVersion to ensure you’re using V2
- Track meta.timestamp for debugging
Verify integrator features
- Test with API key authentication
- Verify fee calculations
- Check outputAmountAfterFee values

Common Issues

Issue: Missing Meta Field

Problem: Response doesn’t include meta field Solution: Ensure you’re using /{network}/v2/* endpoints, not /{network}/*

Issue: Integrator Features Not Working

Problem: Integrator parameters are ignored Solution:

Obtain an API key: Generate and manage your API keys at the Fibrous Partnership Portal
Verify API key is included in request headers as X-API-Key
Check that integrator address is valid
Ensure only one of fee or surplus is set

Issue: Route and Calldata Endpoint Returns 404

Problem: /{network}/v2/routeAndCalldata not found Solution: This endpoint is V2-only. Use /{network}/v2/routeAndCalldata (not /{network}/routeAndCalldata) Note: If you were using V1’s /calldata endpoint, remember it’s now /v2/routeAndCalldata in V2.

Issue: Endpoint Name Confusion

Problem: Confused about which V2 endpoint to use Solution: Use this mapping guide:

What You Need	V1 Endpoint	V2 Endpoint
Get route only	`/{network}/route`	`/{network}/v2/route`
Get route + calldata in one call	`/{network}/calldata`	`/{network}/v2/routeAndCalldata`
Generate calldata from existing route	`/{network}/execute`	`/{network}/v2/calldata`

Key Points:

V1’s /calldata → V2’s /routeAndCalldata (GET request, gets route and calldata together)
V1’s /execute → V2’s /calldata (POST request, generates calldata from route)

Next Steps

Review V2 Route Endpoint documentation
Check V2 Calldata Endpoint for POST endpoint details
Explore Integrator Features for monetization

Support

If you encounter issues during migration:

Check our FAQ
Join our Discord for community support
Contact us at contact@fibrous.finance

Getting Started

Chains, Tokens, Contracts

Core Endpoints

Core Endpoints V2

Starknet API

Smart Contracts

Overview

Quick Reference: Endpoint Mapping

What’s New in V2

Integrator Features

Enhanced Metadata

Endpoint Reorganization

Improved Structure

Key Differences

Response Structure

Endpoint Mapping

Integrator Features

Migration Steps

Step 1: Update Base URL

Step 2: Handle Meta Field

Step 3: Update Route Endpoint

Step 4: Update Calldata Endpoint (V1 → routeAndCalldata V2)

Step 5: Update Execute Endpoint (V1 → calldata V2)

Step 6: Handle Integrator Features (Optional)

Parameter Changes

New Optional Parameters

Response Field Changes

Code Examples

Complete Migration Example

With Integrator Features

Backward Compatibility

Testing Your Migration

Common Issues

Issue: Missing Meta Field

Issue: Integrator Features Not Working

Issue: Route and Calldata Endpoint Returns 404

Issue: Endpoint Name Confusion

Next Steps

Support

​Overview

​Quick Reference: Endpoint Mapping

​What’s New in V2

Integrator Features

Enhanced Metadata

Endpoint Reorganization

Improved Structure

​Key Differences

​Response Structure

​Endpoint Mapping

​Integrator Features

​Migration Steps

​Step 1: Update Base URL

​Step 2: Handle Meta Field

​Step 3: Update Route Endpoint

​Step 4: Update Calldata Endpoint (V1 → routeAndCalldata V2)

​Step 5: Update Execute Endpoint (V1 → calldata V2)

​Step 6: Handle Integrator Features (Optional)

​Parameter Changes

​New Optional Parameters

​Response Field Changes

​Code Examples

​Complete Migration Example

​With Integrator Features

​Backward Compatibility

​Testing Your Migration

​Common Issues

​Issue: Missing Meta Field

​Issue: Integrator Features Not Working

​Issue: Route and Calldata Endpoint Returns 404

​Issue: Endpoint Name Confusion

​Next Steps

​Support

Overview

Quick Reference: Endpoint Mapping

What’s New in V2

Key Differences

Response Structure

Endpoint Mapping

Integrator Features

Migration Steps

Step 1: Update Base URL

Step 2: Handle Meta Field

Step 3: Update Route Endpoint

Step 4: Update Calldata Endpoint (V1 → routeAndCalldata V2)

Step 5: Update Execute Endpoint (V1 → calldata V2)

Step 6: Handle Integrator Features (Optional)

Parameter Changes

New Optional Parameters

Response Field Changes

Code Examples

Complete Migration Example

With Integrator Features

Backward Compatibility

Testing Your Migration

Common Issues

Issue: Missing Meta Field

Issue: Integrator Features Not Working

Issue: Route and Calldata Endpoint Returns 404

Issue: Endpoint Name Confusion

Next Steps

Support