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 supported cross-chain and on-chain operations:

1. Swaps across 50+ supported chains, including Ethereum, Tron, Solana, Bitcoin, and other networks.

   • Cross-chain swaps: Swap supported tokens across supported blockchain networks.

   • On-chain swaps: Swap supported token pairs on a supported network.

2. Interchain communication

   Transfer tokens to third-party protocols.

3. Cross-chain zapping

   Zap supported tokens into a Symbiosis-managed liquidity pool.

4. Bridging

   Mint or burn protocol tokens used for transfers between supported chains and the Symbiosis Host Chain. This feature is mainly used for tokens that support Symbiosis cross-chain swap infrastructure. It is not a general-purpose bridge for any token to any chain.

   For more details, see Symbiosis sTokens and Supported Chains.

   If a custom token needs to be bridged, it requires additional review and setup on the Symbiosis side. This is handled separately from the standard API integration flow.

5. Cross-chain operation status tracking

   Retrieve transaction status updates.

Note: “Supported tokens” and “supported token pairs” refer to tokens that can be exchanged through available Symbiosis routes and supported liquidity sources.

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.

Swap Workflow Using the Symbiosis API

Partner ID

partnerId is a custom identifier used to associate swaps and other operations with a specific partner integration. The value is defined by the integrator and can be any string. It is recommended to use the same partnerId consistently across all requests so related transactions can be tracked and attributed correctly.

No registration or setup is required. Choose a fixed identifier for your integration and include it in the X-Partner-Id header of every request to the Symbiosis API. Example:

curl -X 'POST' \
  'https://api.symbiosis.finance/crosschain/v2/quote' \
  -H 'accept: application/json' \
  -H 'X-Partner-Id: YourPartnerId' \
  -H 'Content-Type: application/json' \

V1 or V2 Endpoint Set

• V2 endpoint set: Extended cross-chain swap endpoints with support for any-to-any routing and Bitcoin swap routes. Recommended for integrations.

• V1 endpoint set: Original cross-chain swap endpoints. Planned for gradual deprecation.

A General Workflow for Performing a Swap Using the Symbiosis API

1. Get a list of supported blockchain networks using /v1/chains

2. Check swap limits (allowed swap amounts) using /v1/swap-limits

3. Get the calldata (payload)

   1. For BTC -> Any, use /v2/quote to receive a quote and /v2/swap to obtain a BTC deposit address and a fresh quote.

   2. For Any -> Any (except BTC -> Any), use /v2/quote

4. If the source token is not a native gas token (for example, an ERC-20 token on an EVM chain), approve the smart contract to spend the user's tokens. Important: 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.

5. Sign and send transaction to trigger a cross-chain swap Since network conditions constantly change, calldata must be regenerated periodically (e.g., every 30 seconds) to ensure it remains valid before execution.

   1. For BTC -> Any, send the quoted amount to the BTC address generated in Step 3.a. This will triggers the cross-chain swap.

   2. For Any -> Any (except BTC -> Any), sign the calldata obtained in Step 3.b using the wallet, then submit the transaction to the source blockchain.

6. Monitor the progress of the swap using /v2/tx/{chainID}/{txHash} This endpoint provides real-time status updates for cross-chain operations.

Swap workflow:

• Any to Any: Symbiosis: Cross-Chain Swaps

• BTC to Any: Symbiosis: To/From BTC

Handling Transactions & Approvals

Smart contract approvals, as well as transaction signing and submission, are performed through the user's wallet (for example, MetaMask, WalletConnect, or Coinbase Wallet) via wallet APIs. These actions are not handled directly by the Symbiosis API and must be initiated by the application through wallet interactions.

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.

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.

Supported Blockchains and Tokens

Supported Blockchains

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

• Mainnet Configuration

You can also retrieve the 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 predefined restrictions on supported tokens, and you may define your own list of tokens if needed.

To retrieve the list of token used in Symbiosis, call the /v2/tokens endpoint.

Token Address Format in Payload

Except for gas tokens and BTC, token addresses in the payload are expected in EVM-style 0x... format.

For EVM networks, this is the regular token contract address.

For non-EVM networks, such as TON, TRON, and Solana, the token identifier is also represented in an EVM-style 0x... format.

The conversion depends on the network:

• TON: the native TON token address is represented as a 0x... identifier derived from its HEX form and reduced to the standard EVM address length. Example: USDT on TON:

• TRON: the address is converted to and from its HEX representation directly. This mapping is reversible.

• Solana: Solana token addresses cannot be deterministically converted to EVM-style addresses. Symbiosis uses predefined internal mappings for Solana token identifiers: 0x000…0001 → Solana token A, 0x000…0002 → Solana token B, etc. To get the list:

  curl -X 'GET' \
    'https://api.symbiosis.finance/crosschain/v2/tokens' \
    -H 'accept: application/json'

Attributes for TON and Solana

For TON and Solana tokens, the payload must also include the original native token address in the attributes field.

In this case, the address field still contains the 0x... API identifier, while the attributes field contains the native token address.

Example for an EVM token:

{
  "tokenAmountIn": {
    "chainId": 1,
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amount": "1000000000",
    "decimals": 6,
    "symbol": "USDC"
  }
}

Example for a TON token:

{
  "tokenAmountIn": {
    "chainId": 85918,
    "address": "0x9328ED75956C38a25f59028B146Fecd3621Dfe",
    "amount": "1000000000",
    "attributes": {
      "ton": "EQCxE6mUtQJKFngfaROTKOt11ZbDiX1kCixRv7Nw2Id_sDS"
    },
    "decimals": 6,
    "symbol": "USDT"
  }
}

If the output token requires a native-address attribute, the same rule applies to tokenOut.

Checking the Payload Format

Integrators can always check the expected payload format for any supported network and token directly in the Symbiosis WebApp:

To do this:

1. Open https://app.symbiosis.finance/.

2. Select the same source and destination networks and tokens.

3. Enter an amount.

4. Open the browser developer console.

5. Go to the Network tab.

6. Find the quote request.

7. Check the Payload section.

Fees

The Symbiosis Protocol facilitates on-chain swaps and cross-chain operations across a wide range of supported blockchain networks. During these operations, the protocol collects several types of fees.

Partners may optionally apply additional fees on top of the standard Symbiosis fees if needed.

Cross-chain Operations

For cross-chain operations, Symbiosis provides dedicated fee collector contracts designed for partners to charge and collect custom fees in addition to the standard protocol fees:

• General Fee Collector: deployed on the Symbiosis chain (the protocol host chain) — used for all cross-chain operations except those to and from the Bitcoin network.

• BTC Fee Collectors: deployed on the BNB Chain, Ethereum, Rootstock, and Citrea — used for operations to and from the Bitcoin network.

For details on how to collect additional fees using these contracts, please refer to Partner Fee Collectors

On-Chain Swaps

For on-chain swaps, Symbiosis uses a separate fee collector contract deployed on each supported blockchain. The protocol does not provide a built-in mechanism for partners to collect additional fees for these operations.

If you need to charge additional fees for on-chain swaps, you must deploy and manage your own fee collector contract independently.