Symbiosis API

Symbiosis API | Symbiosis Finance | Swagger

What is the Symbiosis API?

The Symbiosis API allows you to integrate the core functionalities of the Symbiosis Protocol into your application, platform, or protocol. It provides decentralized cross-chain swaps and liquidity management, enabling users to interact with multiple blockchain networks without intermediaries.

Symbiosis Protocol Features Available via the API

The Symbiosis API provides access to the following cross-chain and on-chain operations:

1. Swaps:

   1. Cross-chain swaps – Swap any token across supported blockchain networks. In short: Symbiosis: Cross-Chain Swaps

   2. On-chain swaps – Swap any token pair on a supported network.

2. Interchain communication – Transfer tokens to third-party protocols. In short: Symbiosis as Interchain Communication Protocol

3. Cross-chain zapping – Zap any token into a Symbiosis-managed liquidity pool. In short: Cross-Chain Zaps

4. Bridging – Mint or burn tokens to transfer assets across chains. In short: Symbiosis Mint-Burn Process

5. Cross-chain operation status tracking – Retrieve real-time transaction status updates.

6. Emergency handling:

   1. Retrieve a list of stuck cross-chain operations.

   2. Generate calldata for reverting transactions.

   In short: Symbiosis & Emergencies

Note Any token & any token pair refer to tokens that can be exchanged on supported DEXs within blockchain networks supported by the Symbiosis Protocol.

Checklist Before Going to Production (Mainnet)

Warning: If any of these checks fail, you put the assets of your users at risk. Therefore, you must not go to Mainnet with real assets and real users. This could result in the loss of your users' assets.

1. Approval of ERC20 Tokens: Always approve users' ERC20 tokens for only one contract — the metaRouterGateway — on each blockchain. Verify the contract addresses for all supported blockchains in this configuration.

2. Contract Existence and Address Validation: Ensure that the contracts used in your integration are deployed on the respective blockchains, and that their addresses on each blockchain match those listed in this configuration.

3. Handling of Calldata: Do not modify, reuse, or cache calldata retrieved from Symbiosis SDKs or API methods.

4. Testing: After deployment to Mainnet, conduct at least one cross-chain operation to ensure proper functionality.

Reminder: Perform this checklist during the initial deployment and after every software update.

Understanding the Symbiosis Protocol

The key components for understanding the Symbiosis Protocol include:

• The Symbiosis Core Contracts Interactions: Symbiosis Routing Contracts.

• Stuck cross-chain operations handling: Symbiosis & Emergencies.

Supported Blockchains and Tokens

Supported Blockchains

Chain-specific values (chain IDs, etc.) can be found in the following configuration:

• Mainnet Configuration

You can also retrieve a list of currently supported blockchains using the /v1/chains endpoint.

Supported Tokens

Using the Symbiosis API, you can operate any token that exists and can be exchanged in DEXs within the blockchains supported by the Symbiosis Protocol. There are no restrictions on the tokens to operate, and you may define your own list of supported tokens if needed.

Swagger API Documentation

The Symbiosis API documentation, powered by Swagger, provides an interactive way to explore and test all endpoints:

• Mainnet Documentation: Access the Swagger interface for the Mainnet environment.

Note on Testnet: While a Testnet environment exists for testing purposes, functionality verified on Testnet does not guarantee the same behavior on Mainnet. We strongly recommend testing directly on Mainnet using low-cost networks and small token amounts.

Fees

The Symbiosis protocol facilitates on-chain swaps and cross-chain operations across a wide range of supported blockchain networks. This section explains how protocol-level fees are handled and how partners can implement additional fee collection mechanisms if needed.

On-Chain Swaps

For on-chain swaps, Symbiosis uses an additional fee collector contract deployed on each supported blockchain.

If you need to charge additional fees on top of the standard Symbiosis fee logic for on-chain swaps, you must deploy and manage your own collector smart contract.

Cross-chain Operations

For most cross-chain operations, Symbiosis вeducts fees for gas on intermediate chains and charges protocol-level cross-chain fees during the execution of the operation.

The fee withholding logic is explained in this document: Symbiosis & Fees.

To apply additional custom fees for cross-chain swaps, you must deploy and manage your own fee collector contract and integrate it into the calldata generation process.

BTC Bridging

For swaps to and from the Bitcoin network, Symbiosis provides a dedicated fee collector contract (address) on BNB Chain. This contract can be used by partners and integrators to collect fees related specifically to BTC bridging.

• Fee Token: syBTC (address) syBTC is a 1:1 BTC-pegged token that can be exchanged on EVM-compatible networks or bridged back to native Bitcoin.

• Collecting Address and Fee Parameters The BTC fee collector contract is administered by Symbiosis. To enable custom fee collection, partners must contact the Symbiosis team to configure the following parameters:

  • Fee recipient address – the address eligible to withdraw collected fees from the contract.

  • Fee model – percentage-based, fixed amount, or a combination of both,

  • Fee value – the actual percentage and/or fixed amount to be charged.

• Collecting Fees To apply your fee configuration during swaps to or from BTC, the fee recipient address must be included in the SwapRequestSchema when calling the Symbiosis API.

  If this address is omitted, no custom fee will be collected during the operation.

• Fee Management Methods

  To interact with the fee collector contract the following methods can be used:

  • collectedFees() – Returns the total fees collected.

  • claimFee() – Withdraws accumulated fees to the configured payout address (method ID: 0x6ebc51e1).

Swap Workflow Using the Symbiosis API

A General Workflow for Performing a Swap Using the Symbiosis API

1. Call /v1/chains to get a list of available blockchain networks.

2. Call /v1/swap-limits to verify swap limits (the minimum and maximum allowed swap amounts).

3. Call /v1/swap to get the calldata (payload) needed to execute the swap through Symbiosis protocol.

4. If the source token is not a native gas token (e.g., ERC-20 tokens on EVM chains), approve the smart contract to spend the user's tokens.

5. Sign the calldata obtained in Step 3 using the wallet. Submit the transaction to the source blockchain. Since network conditions constantly change, calldata must be regenerated periodically (e.g., every 30 seconds) to ensure it remains valid before execution.

6. Call /v1/tx/{chainID}/{txHash} to monitor the progress of the swap. This endpoint provides real-time status updates for cross-chain operations.

Handling Transactions & Approvals

Approving smart contracts, signing, and sending transactions are performed through the user's wallet (e.g., MetaMask, WalletConnect, Coinbase Wallet) using wallet APIs. These actions are not handled directly by the Symbiosis API but must be performed via wallet interactions initiated by the application.

Checking API Health & Swap Time

An application can perform health checks periodically or before each swap using /health-check. The frequency depends on the app's load and expected behavior.

To get an approximate swap duration, use the swap time estimation endpoint /v1/swap-durations. The estimated swap time is based on historical data and a real swap time may vary due to changing network conditions.

Examples

Symbiosis WebApp

The Symbiosis WebApp uses the Symbiosis API for interacting with the Symbiosis Protocol and serves as a reference for supported protocol functionalities.

Swagger

The Swagger documentation of the Symbiosis API provides examples for every endpoint. Simply scroll to the endpoint of interest, input the required data, or use preset values, and execute the example.

For instance, there are preset token pairs for cross-chain swapping: