# Error Handling Source: https://docs.rubic.finance/api-docs/about/core-concepts/error-handling This page explains how errors are structured in the Rubic API, how error codes are formed, and how they should be handled during quote and swap execution. ## **Error code format** Each error code is a **6-digit number** composed of two parts: | **Part** | **Description** | | :------------------ | :-------------------------------------------- | | Error domain | Identifies the stage where the error occurred | | Specific error code | Describes the exact failure reason | The final error code is formed by concatenating both parts and converting them to a number. **Example** If a requested token pair is not supported: * Error domain: 002 * Specific error code: 001 * Final error code: **2001** Errors are always tied to a specific stage of the API flow, such as: * quote calculation * swap execution * smart contract interaction ## **Error domains** | **Domain** | **Code** | **Description** | | :---------------------- | :------- | :-------------------------------------- | | `PARAMS_ERRORS` | 001 | Request validation and input parameters | | `CALCULATION_ERRORS` | 002 | Route discovery and quote calculation | | `SWAP_ERRORS` | 003 | Swap execution | | `RUBIC_CONTRACT_ERRORS` | 004 | Rubic smart contracts | | `UNKNOWN_ERRORS` | 999 | Unexpected or unknown errors | ## **Params errors (001)** Errors related to invalid or missing request parameters. | **Code** | **Name** | **Description** | | :------- | :--------------------------- | :----------------------------------------- | | 001 | `REQUIRED_RECEIVER` | Receiver address is required | | 002 | `EQUAL_TOKENS` | Source and destination tokens are the same | | 003 | `DIFFERENT_QUOTES` | Quote data mismatch | | 004 | `MISS_ID` | Required identifier is missing | | 005 | `NO_REQUIRED_FIELD` | One or more required fields are missing | | 006 | `NOT_CORRECT_WALLET_ADDRESS` | Invalid wallet address | | 999 | `WRONG_OR_MISSED_FIELD` | Invalid or malformed field | ## **Calculation errors (002)** Errors occurring during route discovery or quote calculation. | **Code** | **Name** | **Description** | | :------- | :---------------------------- | :------------------------------------------ | | 001 | `NO_ROUTES` | No routes found for the provided parameters | | 002 | `BLOCKCHAIN_TEMPORARILY_DOWN` | Blockchain is temporarily unavailable | | 003 | `PROVIDER_RATE_LIMIT` | Provider rate limit exceeded | | 004 | `MAX_AMOUNT` | Amount exceeds provider limits | | 005 | `MIN_AMOUNT` | Amount below provider limits | | 006 | `MAX_DECIMALS` | Token decimals exceed allowed limit | | 007 | `NO_AUTH_WALLET` | Wallet authorization is required | | 999 | `UNKNOWN` | Unknown calculation error | ## **Swap execution errors (003)** Errors occurring during swap execution. | **Code** | **Name** | **Description** | | :------- | :-------------------------- | :--------------------------------------- | | 001 | `NEED_APPROVE` | ERC20 approval is required | | 002 | `NEED_PERMIT2_APPROVE` | Permit2 approval is required | | 003 | `NOT_ENOUGH_BALANCE` | Insufficient token balance | | 004 | `NOT_ENOUGH_NATIVE_BALANCE` | Insufficient native currency for fees | | 005 | `SIMULATION_FAILED` | Transaction simulation failed | | 006 | `UNSUPPORTED_RECEIVER` | Receiver address is not supported | | 007 | `NO_DATA` | Execution data is missing | | 100 | `WRONG_ARB_BRIDGE_HASH` | Invalid Arbitrum bridge transaction hash | | 999 | `UNKNOWN` | Unknown swap execution error | ## **Rubic contract errors (004)** Errors related to Rubic smart contract configuration. | **Code** | **Name** | **Description** | | :------- | :----------------- | :----------------------------------- | | 001 | `NO_DIRECT_ROUTES` | No direct routes available | | 002 | `NO_SELECTOR` | Required function selector not found | | 003 | `NO_CONTRACT` | Contract not deployed or unavailable | | 004 | `UNLISTED` | Contract or token is not listed | ## **Error response formats** The API may return errors in different formats depending on the error domain. ## **Validation errors (PARAMS\_ERRORS)** Validation errors may contain **multiple issues** in a single response. | **Field** | **Description** | | :-------- | :------------------------------- | | code | Error code | | reason | Human-readable error description | Example: * Invalid sender address * Invalid receiver address ## **Standard error response** All errors except validation errors follow a unified response structure. | **Field** | **Description** | | :------------------------------ | :-------------------------------- | | error.code | Numeric error code | | error.reason | Human-readable error description | | [error.data](http://error.data) | Optional additional error details | | id | Swap or execution identifier | The id field can be used to track the swap or retrieve its status if execution was partially completed. *** ## **Common error examples** ### **No routes available** | **Field** | **Value** | | :-------- | :--------------------------------------- | | code | 2001 | | reason | No routes found. Try to use other tokens | ### **Approval required** Returned when the user does not have enough allowance for a required spender. | **Field** | **Value** | | :------------------- | :--------------------------------------- | | code | 3001 | | reason | Not enough allowance for spender address | | data.contractAddress | Spender contract address | ### **Insufficient native balance (EVM)** | **Field** | **Description** | | :------------ | :------------------------------------------------- | | code | 3004 | | reason | Not enough native currency to pay transaction fees | | data.gasLimit | Estimated gas limit | | data.gasPrice | Estimated gas price | | data.value | Transaction value | ### **Insufficient native balance (TON)** | **Field** | **Description** | | :--------- | :--------------------------------------------- | | code | 3004 | | reason | Not enough native currency to pay network fees | | data.gas | Estimated gas amount | | data.value | Transaction value | ## **Notes** * Not all errors include the data field * Error lists may expand as the API evolves * Refund handling depends on the selected provider * Some providers (for example, Celer) require manual refund actions via a dedicated endpoint or support # Refunds Source: https://docs.rubic.finance/api-docs/about/core-concepts/refunds Refund handling depends on the selected provider. In most cases, refunds are processed automatically by the provider and do not require any action from the client or the user. ### **Automatic refunds** For the majority of providers: * refunds are triggered automatically * no additional API calls are required * the client only needs to track the transaction status until it is resolved ### **Manual refunds (Celer)** For **Celer-based routes**, refunds require an explicit action. Rubic provides a [dedicated refund endpoint](https://docs.relay.link) that returns the transaction data required to execute a refund on-chain. **Available options** * Use the dedicated **Celer refund endpoint** described in this documentation * Contact **Rubic support** if manual assistance is required ### **Notes** * Refund availability and execution logic are **provider-specific** * Not all routes support manual refunds * If a refund endpoint is not available for a provider, refunds are handled automatically or via support # Understanding Flow Execution Source: https://docs.rubic.finance/api-docs/about/core-concepts/understanding-flow-execution Rubic does not split swaps into multiple exec ### **1) EVM (decentralized)** **Description** Decentralized EVM routes are executed via a smart contract call. **Returned data** * `to` — contract address * `data` — encoded contract call * `value` — native value attached to the transaction **Client behavior** * Send an EVM transaction using to, data, and value * Track the transaction until completion ### **2) EVM (deposit)** **Description** Deposit-based EVM routes are executed by transferring funds to a deposit address on an EVM chain. **Returned data** * `to` — token contract address (or deposit address for native token swap) * `data` — encoded transfer (or 0x for native token swap) * `value` — 0 (or transfer amount for native token swap) **Client behavior** * Send an EVM transaction transferring value to to with the provided data * Track execution using the provided identifiers ### **3) non-EVM (decentralized)** **Description** Decentralized non-EVM routes are executed using a **native transaction format** specific to the target blockchain. **Returned data** * a blockchain-specific transaction object **Supported networks** * TON * Tron * Solana * Sui **Client behavior** * Sign and send the returned transaction using the native wallet / SDK of the corresponding blockchain * Track the transaction until completion ### **4) non-EVM (deposit)** **Description** Deposit-based non-EVM routes are executed via a **manual deposit transfer**. **Returned data** * `depositAddress` * `amountToSend` **Client behavior** * Transfer `amountToSend` to `depositAddress` from the user wallet * Track execution using the provided identifiers ## **Summary** | **Execution type** | **User action** | | :---------------------- | :---------------------------- | | EVM (decentralized) | Contract call | | EVM (deposit) | Transfer to deposit address | | non-EVM (decentralized) | Native blockchain transaction | | non-EVM (deposit) | Manual deposit transfer | # Fee sharing via decentralized providers Source: https://docs.rubic.finance/api-docs/about/monetization/evm To start the process of receiving commissions, please provide our [Business Development team ](https://t.me/RubicPartnership)with the following details: 1. An EVM address for fee sharing. If you’d like to use various fee models, please provide different EVM wallets for each fee value. 2. The fee model you would like to use: Percentage-based, Fixed Amount, or Mixed. Please find a detailed description of each model [here](https://dev-docs.rubic.exchange/api-docs/about/monetization/overview). 3. The fee value: * *percentage fee value* for the Percentage-based model; * *amount in USD* for the Fixed Amount model; * *amount in USD* and *the percentage value* for the Mixed model. After receiving the required details, we'll list your address(es) on our side, and it will be necessary to set it as the `integratorAddress` in the requests to the Rubic API. If the `integratorAddress` is not specified, the default fixed fee in native tokens will be deducted from each transaction. # Fee sharing via deposit-based providers Source: https://docs.rubic.finance/api-docs/about/monetization/non-evm This page is under development. Fee sharing from non-EVM chains is currently available via ChangeNOW, Changelly, Exolix and Near Intents. Fees are shared for cross-chain transactions across all networks supported by these providers, including both EVM and non-EVM networks. ### **How does fee sharing via deposit-based providers work?** Fee sharing for transactions performed via deposit-based providers consists of several **key steps**: 1. The integrator sends requests to the Rubic API, indicating their previously whitelisted EVM `integratorAddress` and `referrer`. 2. Based on the provided address, Rubic identifies that the trade was executed through the corresponding integrator. 3. Users perform transactions on the integrators’ platforms and pay fees, which providers credit to the Rubic address. Only the percentage-based fee model is applied. 4. Rubic calculates the integrator’s share based on internal swap statistics. 5. The commission is transferred manually once per month to the `integratorAddress`, based on the internal swap statistics. ## 💡 FAQ 1. **In which network are commissions credited?** Binance Smart Chain (BNB Chain) or Ethereum. 2. **In which token are commissions credited?** USDT token. 3. **What’s the size of the commission?** The total commission for transactions via deposit-based providers  is 1%, shared equally between Rubic (0.5%) and an integrator (0.5%). The total fee value can be changed upon request. 4. **How often do integrators receive commissions for transactions via ChangeNOW?** Once a month, the fees are transferred to the whitelisted `integratorAddress`. For address listing, please contact our [Business Development team](https://t.me/RubicPartnership). 5. **Do integrators need to indicate non-EVM addresses in the integratorAddress field for transactions from non-EVM networks?** No – commissions are always paid in USDT on BNB Chain or Ethereum, so non-EVM addresses are not required. 6. **What if we have multiple addresses for collecting commissions? Which address will be used for fee sharing?** In this case, you need to inform the Rubic team which listed address should be used to receive commissions for transactions processed via deposit-based providers. 7. **Should integrators continue passing the whitelisted EVM address even for transactions from non-EVM chains?** Yes - the listed EVM wallet address is used by Rubic to link swaps to the integrator. This address should be passed consistently across all chains in the `integratorAddress` field. In addition, including the `referrer` parameter in API requests is required to properly track the origin of each transaction. # Monetization Source: https://docs.rubic.finance/api-docs/about/monetization/overview Customize, monetize, and simplify with Rubic. ## **What revenue sharing models do we have?** ### **1. Percentage-Based Commission:** You can set any percentage (e.g., 0.01% or 2.1%) of the total swap amount. There are no limits. The fee is deducted in the user's initial asset. * Example #1: A user swaps ARB (Arbitrum) for USDC (Base). The fee is paid in ARB, and the integrator earns income in ARB. * Example #2: If a user swaps 100 USDT on Polygon with a 1% commission, 99 USDT goes into the trade, and 1 USDT is sent to Rubic’s contract, where it is shared between the integrator and Rubic. ### **2. Fixed Amount Commission:** The fee is charged in the native gas token of the source network. Integrators can define the fee in USD, and we will automatically convert it into the corresponding native asset of the respective blockchain. * Example: A user swaps USDT (Polygon) for ETH (Blast). The fee is paid in POL (excluding gas fees), and the integrator earns income in POL. ### **3. Percentage + Fixed Amount Commission:** The fee combines a percentage of the user's initial asset token and the source network’s native gas token. * Example: A user swaps DAI (BNB Chain) for USDT (Optimism). The fees are paid in both BNB (BNB Chain gas token) and DAI (user's initial asset), excluding gas fees (network fee). The integrator earns income in both BNB and DAI. In case models for on-chain and cross-chain transactions are different, you should send us two wallet addresses. One will be used for on-chain commission receiving, the second one for cross-chain. # Swagger & OpenAPI Source: https://docs.rubic.finance/api-docs/about/open-api Rubic API provides an interactive Swagger UI generated from its OpenAPI specification. Swagger is intended to help integrators explore available endpoints, inspect request and response schemas, and test API calls. ## **Swagger UI** The Swagger UI is available at: [https://api-v2.rubic.exchange/api/swagger/](https://api-v2.rubic.exchange/api/swagger/) It always reflects the **current state of the API** and is generated directly from the OpenAPI specification. ## **OpenAPI specification** Rubic API is described using **OpenAPI 3.x**. The specification defines: * available endpoints and HTTP methods * request parameters and request bodies * response schemas * error response formats Swagger UI is a visual representation of this specification. ## **Raw OpenAPI files** In addition to Swagger UI, Rubic provides direct access to the raw OpenAPI specification files. These files can be used for: * generating API clients * importing into tools like Postman or Insomnia * validating requests and responses * offline inspection of the API schema Available formats: * JSON: [https://api-v2.rubic.exchange/api/routes/swagger-json](https://api-v2.rubic.exchange/api/routes/swagger-json) * YAML: [https://api-v2.rubic.exchange/api/routes/swagger-yaml](https://api-v2.rubic.exchange/api/routes/swagger-yaml) ## **What Swagger is useful for** Swagger is best suited for: * discovering available endpoints * understanding request and response structures * checking required and optional fields * testing API calls in an isolated environment It is especially useful during early integration and debugging. ## **Using Swagger for testing** You can execute requests directly from Swagger UI. Typical flow: 1. Open the Swagger UI 2. Select an endpoint 3. Click **Try it out** 4. Fill in the required parameters 5. Execute the request 6. Inspect the response Responses returned by Swagger are identical to real API responses. ## **Versioning and updates** The Swagger UI and OpenAPI files always represent the **latest version** of the API. As the API evolves: * new fields or endpoints may be added * existing fields may become deprecated Integrators should follow the documentation and changelog when updating integrations. # Overview Source: https://docs.rubic.finance/api-docs/about/overview Rubic API is a unified interface for building on-chain and cross-chain swap integrations. It allows applications to discover available routes, calculate swap results, execute swaps, and track transaction status across multiple blockchains and providers. The API abstracts away provider-specific logic and execution differences, exposing a consistent flow for integrators. ## **What Rubic API is used for** Rubic API is designed to help developers: * build token swap functionality * support cross-chain transfers * aggregate liquidity from multiple providers * handle both EVM and non-EVM blockchains through a single API * avoid direct integration with multiple DEXes and bridges The API focuses on **route discovery, execution data generation, and transaction status tracking**, while leaving UI and user interaction fully under the integrator’s control. ## **Who Rubic API is for** Rubic API is intended for: * wallets * DeFi applications * aggregators * trading interfaces * backend services executing swaps on behalf of users It is suitable for both frontend and backend integrations and does not impose UI or UX constraints. ## **Supported execution models** Rubic API supports different execution models depending on the selected route and blockchain combination: * EVM contract-based swaps * EVM deposit-based swaps * non-EVM native transactions (TON, TRON, Solana, Sui) * manual deposit-based execution for non-EVM routes All execution details are returned by the API and must be executed by the integrator. ## **Core integration flow** A typical integration with Rubic API consists of three main stages: 1. **Quote** 2. **Swap** 3. **Transaction status tracking** ## **Step 1: Quote** The quote endpoints are used to calculate possible swap routes and expected output amounts. At this stage, the API: * evaluates available DEXes, bridges, and providers * calculates output amounts and fees * returns route information and estimated results Quotes are **indicative** and may change before execution. ## **Step 2: Swap** The swap endpoints are used to request **execution data** for a selected route. At this stage, the API: * recalculates the output amount * returns the exact data required to execute the swap * provides execution instructions depending on the route type The API does **not automatically execute transactions**. The integrator is responsible for sending transactions or performing deposit transfers. If the output amount differs from the quoted amount, the integrator must handle user confirmation before proceeding. ## **Step 3: Transaction status check** After execution is initiated, the integrator can track swap progress using the provided identifiers. Transaction status tracking allows: * monitoring cross-chain execution * checking whether the destination transaction was completed * handling partial execution or failures Status tracking is especially important for cross-chain and deposit-based routes. ## **Typical integration flow** 1. User selects tokens and amount 2. Application requests a quote 3. User confirms the quote 4. Application requests swap execution data 5. Application executes the transaction or deposit 6. Application tracks transaction status until completion ## **Important notes** * Quotes are not guaranteed and may change * Swap execution may return updated amounts * Integrators must handle user confirmations explicitly * Execution logic differs by provider and blockchain # Referrer and Rate limits Source: https://docs.rubic.finance/api-docs/about/referrer ## Referrer The **referrer** is a unique identifier included in requests to the Rubic API that helps us track the origin of API calls. Please indicate the `referrer` parameter in each API request in accordance with your project's title. For example, your project is "TestSwap", in this case, please pass `testswap` as a referrer. This will help us identify that transactions are calculated and performed on your platform. ## Rate limits | Rubic API endpoint types | Endpoints | Limits | | ----------------------------------------------------------------- | ------------------- | ------------ | | Standard Rubic API endpoint (no API key) | `api-v2` | 10 RPM | | Rubic API endpoint with increased limits (an API key is required) | `pro-api-v2` | 400 RPM | | Dedicated Rubic API domain (an API key is required) | `integrator-api-v2` | Customizable | If the rate limits of the standard Rubic API endpoint are not sufficient for your use case, access to **pro-api-v2** with extended limits can be provided. To obtain access to **pro-api-v2**, please contact our [Business Development team](https://t.me/RubicPartnership) to discuss the details and receive an API key. The API key for **pro-api-v2** (as well as for a dedicated subdomain, if applicable) should be passed via request headers: ```javascript theme={null} headers={ "apikey": "your_api_key" } ``` # Transaction Statuses Explained Source: https://docs.rubic.finance/api-docs/general/status/explain This page explains the meaning of each transaction status you may encounter while tracking a cross-chain transaction. Use it to understand the current state of a transaction, identify potential issues, and determine whether any additional action is required. | Status | Explanation | | :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 💤 PENDING | The transaction is in progress | | 💤 NOT\_FOUND | The transaction indexing is in progress, or the provider’s status API did not return the transaction status | | ✴️ REVERTED | The transaction on the destination chain was not completed and a refund was issued | | ✅ READY\_TO\_CLAIM | Tokens can be claimed on the destination network. This status applies only to the token claim on the destination chain for transactions involving the bridge of RBC tokens between Ethereum and Arbitrum via the Arbitrum Bridge | | ✅ SUCCESS | The transaction on the destination chain is successful | | ❌ FAIL | Transaction on the destination chain failed | | 🔒 KYC\_REQUIRED | KYC is not required for starting an exchange via the Rubic API. Deposit-based providers may request passing KYC to verify user identities, ensure transaction legitimacy, and comply with international laws and industry standards. Please find more details here | # Prevent dangerous routes Source: https://docs.rubic.finance/api-docs/guides/dangerous-routes How to prevent swaps via routes with high slippage or price impact In `/quote` and `/quoteBest` you can pass a parameter `showDangerousRoutes: false` to filter routes with priceImpact more than -5% and less than +20% and slippage more than 20%(slippage: 0.2). Price impact is estimated as: ```javascript theme={null} srcTokenAmountInUsd = srcTokenAmount * srcTokenPrice dstTokenAmountInUsd = dstTokenAmount * dstTokenPrice priceImpact = ((srcTokenAmountInUsd - dstTokenAmountInUsd) / dstTokenAmountInUsd) * 100 ``` By default `showDangerousRoutes` is optional property and set to `false`. If you pass `showDangerousRoutes: true` - you will receive in response every route that was successully found in spite of priceImpact and slippage values. Example of request to show only safe routes: ```javascript theme={null} { "dstTokenAddress":"0x1f9840a85d5af5bf1d1762f925bdaddc4201f984", "dstTokenBlockchain":"ETH", "integratorAddress":"0x3019BD6BA7CEE183298385958dDE8d67DfCc2340", "referrer":"arbitragescanner", "srcTokenAddress":"0xdac17f958d2ee523a2206206994597c13d831ec7", "srcTokenAmount":"100000000", "srcTokenBlockchain":"ETH", "showDangerousRoutes": false } ``` # Handling amount changes during swap Source: https://docs.rubic.finance/api-docs/guides/handling-amount-change During swap execution, the output amount may differ from the amount returned during the quote step. This behavior is expected and can occur due to price movements, liquidity changes, or provider recalculation. The API **does not explicitly indicate** that the amount has changed beyond an acceptable threshold. It always returns the **latest calculated amount**, and it is the **integrator’s responsibility** to detect significant changes and request user confirmation. ## **Key responsibility of the integrator** When performing a swap, the integrator must: * store the output amount returned by quote * compare it with the output amount returned by swap * detect significant deviations * explicitly confirm the new amount with the user * send a **new swap request** only after user approval Automatic execution without user confirmation is **not recommended** when the amount changes significantly. ## **Why amount changes happen** | **Reason** | **Description** | | :--------------------- | :------------------------------------------------- | | Market movement | Token prices may change between quote and swap | | Liquidity updates | Available liquidity on DEXes or bridges may change | | Provider recalculation | Providers may recalculate output during execution | Because of this, the amount returned by swap should always be treated as **final and authoritative**. ## **Recommended deviation threshold** Rubic recommends using a **±0.5%** deviation threshold. If the new amount exceeds this range compared to the quoted amount, the integrator should pause execution and request user confirmation. ## **Recommended execution flow** | **Step** | **Action** | | :------- | :---------------------------------------------------- | | 1 | Call quote and store toTokenAmount | | 2 | User confirms and initiates swap | | 3 | Call swap and receive updated toTokenAmount | | 4 | Compare quote amount with swap amount | | 5 | If deviation is above threshold, show confirmation UI | | 6 | If user approves, send a **new swap request** | | 7 | If user rejects, cancel execution | ## **Amount comparison example** The following example checks whether the new amount differs from the quoted amount by more than 0.5%. ```typescript theme={null} const changePercent = 0.5; const acceptablePercent = new BigNumber(changePercent).dividedBy(100); const oldAmount = new BigNumber(oldWeiAmount); const newAmount = new BigNumber(newWeiAmount); const upperBound = oldAmount.multipliedBy(acceptablePercent.plus(1)); const lowerBound = oldAmount.multipliedBy(new BigNumber(1).minus(acceptablePercent)); const isOutOfRange = newAmount.lt(lowerBound) || newAmount.gt(upperBound); if (isOutOfRange) { throw new AmountChangeWarning(oldWeiAmount, newWeiAmount); } ``` ## **Handling amount change on the client** When an amount change is detected, the integrator should pause execution and notify the user. ### **Example handling logic** ```typescript theme={null} if (err instanceof AmountChangeWarning) { const rateChangeInfo = { oldAmount: Token.fromWei(err.oldAmount, trade.to.decimals), newAmount: Token.fromWei(err.newAmount, trade.to.decimals), tokenSymbol: trade.to.symbol }; const allowSwap = await onRateChange(rateChangeInfo); if (allowSwap) { // retry swap } } ``` ## **User confirmation UI** The integrator may choose any UI approach, as long as the confirmation is **explicit**. ### **Common UI patterns** * confirmation modal * inline warning with accept / cancel buttons * full-screen confirmation step (mobile) ### **Recommended confirmation content** | **Field** | **Description** | | :-------------- | :---------------- | | Previous amount | Amount from quote | | New amount | Amount from swap | | Token symbol | Destination token | | Action | Continue / Cancel | ## **Important notes** * The API **does not signal** that the amount change is significant * The integrator must perform the comparison manually * Users must explicitly approve any significant change * A new swap request is required after confirmation * Silent or automatic acceptance is strongly discouraged # Get available providers Source: https://docs.rubic.finance/api-reference/info/get-available-providers https://api-v2.rubic.exchange/api/routes/swagger-json get /api/info/providers This endpoint returns a list of supported providers available for swaps in the Rubic API. Each provider object contains list of supported by provider blockchains and provider name used in the API. Contains separate information for cross-chain providers and on-chain providers # Get chains list Source: https://docs.rubic.finance/api-reference/info/get-chains-list https://api-v2.rubic.exchange/api/routes/swagger-json get /api/info/chains This endpoint returns a list of supported blockchains available for exchange and transactions in the Rubic API. Each blockchain object contains a name, an identifier, list of providers that support this blockchain, the type of blockchain and whether fee collection is available in this blockchain (proxyAvailable field) # Get transaction status Source: https://docs.rubic.finance/api-reference/info/get-transaction-status https://api-v2.rubic.exchange/api/routes/swagger-json get /api/info/statusExtended You can check the status of your cross-chain transaction by providing the source transaction hash and/or the id received in the /swap response. The statusExtended response includes the transaction status on the destination chain and, if successful, the destination blockchain transaction hash. For decentralized providers, both the source transaction hash and the id are required. For deposit-based providers only the id is required. # Get all available quotes Source: https://docs.rubic.finance/api-reference/router/get-all-available-quotes https://api-v2.rubic.exchange/api/routes/swagger-json post /api/routes/quoteAll Using this endpoint, you can get a preview of all possible routes for a cross-chain or on-chain swaps. The router goes through all supported DEXes, bridges, and aggregators to find and return all available routes. All routes are sorted by expected swap output, allowing you to easily compare different options and select the most suitable route before executing the swap. # Get all available quotes via deposit Source: https://docs.rubic.finance/api-reference/router/get-all-available-quotes-via-deposit https://api-v2.rubic.exchange/api/routes/swagger-json post /api/routes/quoteDepositTrades Using this endpoint, you can get a preview of all possible deposit routes for a cross-chain swap. The router goes through all supported deposit-based bridges and providers to find and return all available deposit trades. # Get best quote Source: https://docs.rubic.finance/api-reference/router/get-best-quote https://api-v2.rubic.exchange/api/routes/swagger-json post /api/routes/quoteBest Using this endpoint, you can get the best available route for a cross-chain or on-chain swap. The router goes through all supported DEXes, bridges, and aggregators to find and return the route with the highest expected swap output. # Get swap data Source: https://docs.rubic.finance/api-reference/router/get-swap-data https://api-v2.rubic.exchange/api/routes/swagger-json post /api/routes/swap Using this endpoint, you can get the transaction data required to execute a swap. The data is generated based on the route selected in the previous step and can be used to send the swap transaction from the user’s wallet. # Get swap data for the best quote Source: https://docs.rubic.finance/api-reference/router/get-swap-data-for-the-best-quote https://api-v2.rubic.exchange/api/routes/swagger-json post /api/routes/swapBest Using this endpoint, you can get the transaction data for executing the best available swap route. The router automatically selects the route with the highest expected swap output and returns the corresponding transaction data, ready to be sent from the user’s wallet. # Get swap data via deposit Source: https://docs.rubic.finance/api-reference/router/get-swap-data-via-deposit https://api-v2.rubic.exchange/api/routes/swagger-json post /api/routes/swapDepositTrade Using this endpoint, you can get the deposit data required to perform a manual transfer to a selected deposit-based provider. The response includes the depositAddress, amountToSend, exchangeId, and optional extraFields, which can be used to manually send funds from the wallet. This data is generated based on the route selected in the previous step and is intended for providers that require a direct deposit instead of an on-chain swap transaction. # Get allowance Source: https://docs.rubic.finance/api-reference/utility/get-allowance https://api-v2.rubic.exchange/api/routes/swagger-json get /api/utility/allowance This endpoint retrieves the current allowance value for an ERC-20 token on the specified blockchain. It is typically used before calling the approve endpoint to decide whether additional approval is needed. # Get approve info Source: https://docs.rubic.finance/api-reference/utility/get-approve-info https://api-v2.rubic.exchange/api/routes/swagger-json get /api/utility/checkApprove This endpoint determines whether a token approval is required on the specified blockchain. If approval is needed, it returns all transaction data required to execute the approval on-chain. # Get celer refund data Source: https://docs.rubic.finance/api-reference/utility/get-celer-refund-data https://api-v2.rubic.exchange/api/routes/swagger-json get /api/utility/celerRefund This endpoint returns the data required to refund a transaction via the Celer Bridge. It is used when a cross-chain transaction cannot be completed and a refund must be executed on the source or destination network. # Get claim tokens data Source: https://docs.rubic.finance/api-reference/utility/get-claim-tokens-data https://api-v2.rubic.exchange/api/routes/swagger-json get /api/utility/claim This endpoint returns the data required to claim or redeem tokens for the Arbitrum Bridge (ETH ↔ Arbitrum). It is used after a successful source-chain transaction to prepare the on-chain call on the destination network. # Get message to auth wallet Source: https://docs.rubic.finance/api-reference/utility/get-message-to-auth-wallet https://api-v2.rubic.exchange/api/routes/swagger-json get /api/utility/authWalletMessage This endpoint provides a message required for wallet authentication when using the Retrobridge provider. The user must sign this message with their wallet, and the resulting signature must be attached to the swap request to enable transaction execution. # Health check Source: https://docs.rubic.finance/api-reference/utility/health-check https://api-v2.rubic.exchange/api/routes/swagger-json get /api/utility/healthcheck This endpoint returns the current health status of the API. It can be used to verify service availability and basic system readiness. # Configuration Source: https://docs.rubic.finance/configuration # Configuration ## SDK.create() ```typescript theme={null} const sdk = await SDK.create(params: SdkParams, httpClient?: HttpClient): Promise ``` The factory method is `async` because it dynamically imports `axios` when no custom HTTP client is provided. *** ## SdkParams | Field | Type | Required | Default | Description | | ------------------------------ | -------- | -------- | -------------- | -------------------------------------------------------------------------------------------------- | | `referrer` | `string` | ✅ | — | Identifies your integration. Sent as `referer` in every request body | | `apiKey` | `string` | | `''` | API key for the Rubic API. Get one at [here](https://t.me/RubicPartnership) | | `integratorAddress` | `object` | | See below | Wallet addresses that collect integrator fees (text our [BD](https://t.me/RubicPartnership) first) | | `integratorAddress.crossChain` | `string` | | `0x3fFF...DbE` | Fee recipient for cross-chain swaps | | `integratorAddress.onChain` | `string` | | `0x3b9C...0d4` | Fee recipient for on-chain swaps | | `timeout` | `number` | | `10000` | Request timeout in ms (default HTTP client only) | ### Example — full configuration ```typescript theme={null} import { SDK } from '@cryptorubic/sdk-lite'; const sdk = await SDK.create({ referrer: 'my-dapp', apiKey: 'YOUR_API_KEY', integratorAddress: { crossChain: '0xYourFeeReceiverForCrossChain', onChain: '0xYourFeeReceiverForOnChain', }, timeout: 15_000, }); ``` ### Example — minimal configuration (no API key) ```typescript theme={null} const sdk = await SDK.create({ referrer: 'my-dapp' }); ``` *** ## Custom HTTP client By default, SDK ships with an axios-based HTTP client. You can swap it out for any client that implements the `HttpClient` interface — useful for environments without Node.js (e.g. Cloudflare Workers, Deno, React Native). ### HttpClient interface ```typescript theme={null} interface HttpClient { get(url: string, options?: { headers?: Record; params?: Record>; }): Promise; post(url: string, body: object, options?: { headers?: Record; }): Promise; } ``` ### Example — using native fetch ```typescript theme={null} import { SDK, HttpClient } from '@cryptorubic/sdk-lite'; const fetchClient: HttpClient = { async get(url, options = {}) { const searchParams = new URLSearchParams( Object.entries(options.params ?? {}).map(([k, v]) => [k, String(v)]) ); const fullUrl = searchParams.size ? `${url}?${searchParams}` : url; const res = await fetch(fullUrl, { headers: options.headers }); if (!res.ok) throw new Error(`HTTP ${res.status}`); return res.json(); }, async post(url, body, options = {}) { const res = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', ...options.headers }, body: JSON.stringify(body), }); if (!res.ok) throw new Error(`HTTP ${res.status}`); return res.json(); }, }; const sdk = await SDK.create({ referrer: 'my-app' }, fetchClient); ``` ### Example — custom axios instance (with interceptors, retries, etc.) ```typescript theme={null} import axios from 'axios'; import { SDK } from '@cryptorubic/sdk-lite'; const axiosInstance = axios.create({ timeout: 20_000 }); axiosInstance.interceptors.response.use( res => res.data, err => Promise.reject(err) ); const sdk = await SDK.create({ referrer: 'my-app' }, axiosInstance); ``` > **Note:** When using a custom axios instance, make sure the response interceptor unwraps `res.data` — otherwise the SDK will receive the full axios response object instead of the API response body. # Swaps from Bitcoin Source: https://docs.rubic.finance/docs/api-docs/integration-examples/swaps-from-bitcoin This page explains how to connect a Web3 wallet, retrieve token quotes and execute a transaction using Rubic API, with examples using CTRL wallet extension. ## Connecting a Web3 Wallet To interact with the blockchain, we first need to connect a wallet. Here are examples using `CTRL wallet.` ```javascript theme={null} async function connectWallet() { if (window?.xfi?.bitcoin) { const wallet = this.window?.xfi?.bitcoin; const accounts = wallet.getAcccounts(); return accounts[0]; } else { console.error("Bitcoin provider not found. Please install Ctrl wallet."); } } ``` ## Retrieving Token Quotes Now that the wallet is connected, we can request token quotes from Rubic API. **Endpoint:** `POST https://api-v2.rubic.exchange/api/routes/quoteBest` ```javascript theme={null} async function quoteBest() { const response = await fetch("https://api-v2.rubic.exchange/api/routes/quoteBest", { method: "POST", headers: { "Content-Type": "application/json", }, body: { "srcTokenAddress": "0x0000000000000000000000000000000000000000", "srcTokenAmount": "0.01", "srcTokenBlockchain": "BITCOIN", "dstTokenAddress": "0x0000000000000000000000000000000000000000", "dstTokenBlockchain": "ETH", "referrer": "rubic.exchange" } }); const data = await response.json(); const { estimate, transaction, id } = data; console.log(estimate); // { // This is an estimated amount you will get after the swap. // "destinationTokenAmount": "0.42498305", // "destinationTokenMinAmount": "0.4122335585", // // "destinationUsdAmount": 835.39, // "destinationUsdMinAmount": 810.33, // // "destinationWeiAmount": "425207819398076439", // "destinationWeiMinAmount": "412451584816134146", // // "durationInMinutes": 5, // "priceImpact": 0.61, // "slippage": 0.03 // } console.log(id); // This is the swap ID. It will be needed later for swap request. return data; } ``` You can get more information about quote endpoint here: [Request Quote](https://dev-docs.rubic.exchange/docs/api-docs/request-quote) ## Retrieving Data to Execute a Transaction To perform a token swap through Rubic API, we need to get the necessary data for the transaction. **Endpoint:** `POST https://api-v2.rubic.exchange/api/routes/swap` ### Rubic API can return 2 kinds of data for transaction: data for transfer and data for psbt transaction. ### 1. Transfer transaction: ```javascript theme={null} async function getSwapData() { const response = await fetch("https://api-v2.rubic.exchange/api/routes/swap", { method: "POST", headers: { "Content-Type": "application/json", }, body: { "srcTokenAddress": "0x0000000000000000000000000000000000000000", "srcTokenAmount": "0.01", "srcTokenBlockchain": "BITCOIN", "dstTokenAddress": "0x0000000000000000000000000000000000000000", "dstTokenBlockchain": "ETH", "referrer": "rubic.exchange" "fromAddress": "USER WALLET ADDRESS", "id": "ID FROM QUOTE STEP", "receiver": "RECEIVER ADDRESS" } }); const result = await response.json(); const { transaction } = result; console.log(transaction); // { // "to": "bc1ptyhru60vv9q57pqvuet5t3fpcyf7x2t2j83gkz3r3kcrhs9srxls4hcws5", // "value": "1000000", // }, return result; } ``` ### 2. PSBT transaction: ```javascript theme={null} async function getSwapData() { const response = await fetch("https://api-v2.rubic.exchange/api/routes/swap", { method: "POST", headers: { "Content-Type": "application/json", }, body: { "srcTokenAddress": "0x0000000000000000000000000000000000000000", "srcTokenAmount": "0.01", "srcTokenBlockchain": "BITCOIN", "dstTokenAddress": "0x0000000000000000000000000000000000000000", "dstTokenBlockchain": "ETH", "referrer": "rubic.exchange" "fromAddress": "USER WALLET ADDRESS", "id": "ID FROM QUOTE STEP", "receiver": "RECEIVER ADDRESS", "publicKey": "PUBLIC KEY OF USER WALLET ADDRESS" } }); const result = await response.json(); const { transaction } = result; console.log(transaction); // { // "psbt": "cHNidP8BAL4CAAAAAX7WtwDo7JF8EsZ+...AFgGARv/uOHXKMXpGDtp5ijUAAAAA", // "signInputs": [0], // }, return result; } ``` You can get more information about swap endpoint here: [Request Data](https://dev-docs.rubic.exchange/docs/api-docs/request-data) ## Executing a Transaction with the API Response Data Using the data obtained from the Rubic API, you can now execute the transaction. ### 1. Transfer transaction: ```javascript theme={null} async function executeSwapViaTransfer( // Transaction object, obtained on previous step from Rubic API transaction, // From wallet address fromAddress, // Recipient wallet address toAddress ) { let hash = null; await window.xfi.bitcoin.request( { method: 'transfer', params: [ { feeRate: 10, from: fromAddress, recipient: toAddress, amount: { amount: transaction.value, decimals: 8 } } ] }, (error, txHash) => { if(error) { console.error(error) } else { hash = txHash; } } ); if(!hash) throw new Error('Failed to transfer funds'); return hash; } ``` ### 2. PSBT transaction: ```javascript theme={null} async function executeSwap( // Transaction object, obtained on previous step from Rubic API transaction, // From wallet address fromAddress, ) { let hash = null; await window.xfi.bitcoin.request( { method: 'sign_psbt', params: { psbt: transaction.psbt, signInputs: { [fromAddress]: transaction.signInputs }, allowedSignHash: 1, broadcast: true } } }, (error, txData) => { if(error) { console.error(error) } else { hash = txData.result.txId; } } ); if(!hash) throw new Error('Failed to sign psbt transaction'); return hash; } ``` ## Track your transaction Now you can track your transaction status **Endpoint:** `GET https://api-v2.rubic.exchange/api/routes/status` ```javascript theme={null} async function getStatus( // Your transaction hash, otained while executing transaction hash ) { const response = await fetch(`https://api-v2.rubic.exchange/api/info/status?srcTxHash=${hash}`); const data = await response.json(); const { status, destinationTxHash } = data; console.log(status); // Current TX status can be one of // 'PENDING' | 'LONG_PENDING' | 'REVERT' | // 'REVERTED' | 'FAIL' | 'READY_TO_CLAIM' | // 'SUCCESS' | 'NOT_FOUND'; console.log(status); // shows the hash on the target network if the transaction // is successfully completed return status; } ``` You can get more information about status endpoint here: [Get cross-chain status](https://dev-docs.rubic.exchange/docs/api-docs/get-crosschain-status) # Swaps from EVM Source: https://docs.rubic.finance/docs/api-docs/integration-examples/swaps-from-evm This page explains how to connect a Web3 wallet, retrieve token quotes, approve tokens, and execute a transaction using Rubic API, with examples using ethers.js, web3.js, and viem. ## Connecting a Web3 Wallet To interact with the blockchain, we first need to connect a wallet. Here are examples using `ethers.js`, `web3.js`, and `viem`. ```javascript theme={null} import { ethers } from "ethers"; async function connectWallet() { if (window.ethereum) { const provider = new ethers.providers.Web3Provider(window.ethereum); await provider.send("eth_requestAccounts", []); const signer = provider.getSigner(); const account = await signer.getAddress(); return account; } else { console.error("Ethereum provider not found. Please install MetaMask."); } } ``` ```javascript theme={null} import Web3 from "web3"; async function connectWallet() { if (window.ethereum) { const web3 = new Web3(window.ethereum); await window.ethereum.enable(); const [account] = await web3.eth.getAccounts(); return account; } else { console.error("Ethereum provider not found. Please install MetaMask."); } } ``` ```javascript theme={null} import { createWalletClient, custom } from 'viem'; import { mainnet } from 'viem/chains'; async function connectWallet() { if (window.ethereum) { const walletClient = createWalletClient({ chain: mainnet, transport: custom(window.ethereum), }); const [account] = await walletClient.requestAddresses(); return account; } else { console.error("Ethereum provider not found. Please install MetaMask."); } } ``` ## Retrieving Token Quotes Now that the wallet is connected, we can request token quotes from Rubic API. **Endpoint:** `POST https://api-v2.rubic.exchange/api/routes/quoteBest` ```javascript theme={null} async function quoteBest() { const response = await fetch("https://api-v2.rubic.exchange/api/routes/quoteBest", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ "srcTokenAddress": "0x0000000000000000000000000000000000000000", "srcTokenAmount": "1.05", "srcTokenBlockchain": "ETH", "dstTokenAddress": "0x0000000000000000000000000000000000000000", "dstTokenBlockchain": "POLYGON", "referrer": "rubic.exchange" }) }); const data = await response.json(); const { estimate, transaction, id } = data; console.log(estimate); // { // This is an estimated amount you will get after the swap. // "destinationTokenAmount": "8248.453781656313882666", // "destinationTokenMinAmount": "8001.000168206624466186", // // "destinationUsdAmount": 2637.13, // "destinationUsdMinAmount": 2558.02, // // "destinationWeiAmount": "8248453781656313882666", // "destinationWeiMinAmount": "8001000168206624466186", // // "durationInMinutes": 5, // "priceImpact": 0.14, // "slippage": 0.03 // } console.log(transaction.approvalAddress); // This is the address you need to give approve to spend tokens. // See next section for details. // 0x3335733c454805df6a77f825f266e136FB4a3333 console.log(id); // This is the swap ID. It will be needed later for swap request. return data; } ``` You can get more information about quote endpoint here: [Request Quote](https://dev-docs.rubic.exchange/docs/api-docs/request-quote) ## Approving Tokens for Transaction Before sending a transaction, you need to approve the token. `Approve` allows a user to authorize a contract or application to manage a specified amount of their tokens, which is necessary for secure interaction with decentralized applications such as exchanges or DeFi protocols. This gives users control over how many tokens can be used, providing an additional layer of security. Below are examples for different libraries. ```javascript theme={null} import { ethers } from "ethers"; import { TOKEN_ABI } from "./TokenABI"; // replace with the correct ABI async function approveToken( // Token address tokenAddress, // Contract to give approve to. // Put here transaction.approvalAddress obtained on previous step spenderAddress, // Amount of tokens to approve. // For security reasons it's better to set approve // amount equal to from amount amount, // Signer object, obtained while ethers.js initializing signer ) { const tokenContract = new ethers.Contract(tokenAddress, TOKEN_ABI, signer); const tx = await tokenContract.approve(spenderAddress, amount); await tx.wait(); console.log("Approval successful:", tx.hash); } ``` ```javascript theme={null} import Web3 from "web3"; import { TOKEN_ABI } from "./TokenABI"; // replace with the correct ABI async function approveToken( // Token addres tokenAddress, // Contract to give approve to. // Put here transaction.approvalAddress obtained on previous step spenderAddress, // Amount of tokens to approve. // For security reasons it's better to set approve // amount equal to from amount amount, // Wallet address account ) { const web3 = new Web3(window.ethereum); const tokenContract = new web3.eth.Contract(TOKEN_ABI, tokenAddress); const tx = await tokenContract.methods.approve(spenderAddress, amount).send({ from: account }); console.log("Approval successful:", tx.transactionHash); } ``` ```javascript theme={null} import { createWalletClient, encodeFunctionData } from 'viem'; import { TOKEN_ABI } from './TokenABI'; // replace with the correct ABI async function approveToken( // Token addr tokenAddress, // Contract to give approve to. // Put here transaction.approvalAddress obtained on previous step spenderAddress, // Amount of tokens to approve. // For security reasons it's better to set approve // amount equal to from amount amount, // Wallet client object, obtained while viem initializing walletClient, // Wallet addres account ) { const txHash = await walletClient.writeContract({ address: tokenAddress, abi: TOKEN_ABI, functionName: 'approve', args: [spenderAddress, amount] }); console.log("Approval successful:", txHash); } ``` ## Retrieving Data to Execute a Transaction To perform a token swap through Rubic API, we need to get the necessary data for the transaction. **Endpoint:** `POST https://api-v2.rubic.exchange/api/routes/swap` ```javascript theme={null} async function getSwapData() { const response = await fetch("https://api-v2.rubic.exchange/api/routes/swap", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ "srcTokenAddress": "0x0000000000000000000000000000000000000000", "srcTokenAmount": "1.05", "srcTokenBlockchain": "ETH", "dstTokenAddress": "0x0000000000000000000000000000000000000000", "dstTokenBlockchain": "POLYGON", "referrer": "rubic.exchange", "fromAddress": "USER WALLET ADDRESS", "id": "ID FROM QUOTE STEP" }) }); const result = await response.json(); const { transaction } = result; console.log(transaction); // { // "approvalAddress": "0x3335733c454805df6a77f825f266e136FB4a3333", // "data": "0xe1fcde8e0000000...00000000000000000000000000000000000000000000000", // "to": "0x3335733c454805df6a77f825f266e136FB4a3333", // "value": "1050785817564594203" // }, return result; } ``` You can get more information about swap endpoint here: [Request Data](https://dev-docs.rubic.exchange/docs/api-docs/request-data) ## Executing a Transaction with the API Response Data Using the data obtained from the Rubic API, you can now execute the transaction. ```javascript theme={null} async function executeSwap( // Transaction object, obtained on previous step from Rubic API transaction, // Signer object, obtained while ethers.js initializing signer ) { const tx = await signer.sendTransaction({ to: transaction.to, data: transaction.data, value: transaction.value, }); await tx.wait(); console.log("Transaction executed:", tx.hash); } ``` ```javascript theme={null} async function executeSwap( // Transaction object, obtained on previous step from Rubic API transaction, // Wallt address account ) { const web3 = new Web3(window.ethereum); const tx = await web3.eth.sendTransaction({ from: account, to: transaction.to, data: transaction.data, value: transaction.value, }); console.log("Transaction executed:", tx.transactionHash); } ``` ```javascript theme={null} async function executeSwap( // Transaction object, obtained on previous step from Rubic AP transaction, // Wallet client object, obtained while viem initializing walletClient, // Wallt addres account ) { const txHash = await walletClient.sendTransaction({ account, to: transaction.to, data: transaction.data, value: transaction.value, }); console.log("Transaction executed:", txHash); } ``` ## Track your transaction Now you can track your transaction status **Endpoint:** `GET https://api-v2.rubic.exchange/api/routes/status` ```javascript theme={null} async function getStatus( // Your transaction hash, otained while executing transaction hash ) { const response = await fetch(`https://api-v2.rubic.exchange/api/info/status?srcTxHash=${hash}`); const data = await response.json(); const { status, destinationTxHash } = data; console.log(status); // Current TX status can be one of // 'PENDING' | 'LONG_PENDING' | 'REVERT' | // 'REVERTED' | 'FAIL' | 'READY_TO_CLAIM' | // 'SUCCESS' | 'NOT_FOUND'; console.log(status); // shows the hash on the target network if the transaction // is successfully completed return status; } ``` You can get more information about status endpoint here: [Get cross-chain status](https://dev-docs.rubic.exchange/docs/api-docs/get-crosschain-status) # Swaps from Solana Source: https://docs.rubic.finance/docs/api-docs/integration-examples/swaps-from-solana This page explains how to connect a Web3 wallet, retrieve token quotes, approve tokens, and execute a transaction using Rubic API, with examples using @solana/web3.js. ## Connecting a Web3 Wallet To interact with the blockchain, we first need to connect a wallet. Here are examples using `@solana/web3.js`. ```javascript theme={null} async function connectWallet() { if (window.solana) { try { const response = await window.solana.connect(); return response.publicKey; } catch (err) { console.error('Connection error:', err.message); } } else { console.log('Solana provider not found. Please install MetaMask'); } } ``` ## Retrieving Token Quotes Now that the wallet is connected, we can request token quotes from Rubic API. **Endpoint:** `POST https://api-v2.rubic.exchange/api/routes/quoteBest` ```javascript theme={null} async function quoteBest() { const response = await fetch("https://api-v2.rubic.exchange/api/routes/quoteBest", { method: "POST", headers: { "Content-Type": "application/json", }, body: { "srcTokenAddress": "So11111111111111111111111111111111111111111", "srcTokenAmount": "1.05", "srcTokenBlockchain": "SOL" "dstTokenAddress": "0x0000000000000000000000000000000000000000", "dstTokenBlockchain": "POLYGON", "referrer": "rubic.exchange" } }); const data = await response.json(); const { estimate, transaction, id } = data; console.log(estimate); // { // This is an estimated amount you will get after the swap. // "destinationTokenAmount": "451.4591", // "destinationTokenMinAmount": "437.915327", // // "destinationUsdAmount": 233.63, // "destinationUsdMinAmount": 226.63, // // "destinationWeiAmount": "451459000000", // "destinationWeiMinAmount": "437915327000", // // "durationInMinutes": 5, // "priceImpact": 0.23, // "slippage": 0.03 // } console.log(id); // This is the swap ID. It will be needed later for swap request. return data; } ``` You can get more information about quote endpoint here: [Request Quote](https://dev-docs.rubic.exchange/docs/api-docs/request-quote) ## Retrieving Data to Execute a Transaction To perform a token swap through Rubic API, we need to get the necessary data for the transaction. **Endpoint:** `POST https://api-v2.rubic.exchange/api/routes/swap` ```javascript theme={null} async function getSwapData() { const response = await fetch("https://api-v2.rubic.exchange/api/routes/swap", { method: "POST", headers: { "Content-Type": "application/json", }, body: { "srcTokenAddress": "So11111111111111111111111111111111111111111", "srcTokenAmount": "1.05", "srcTokenBlockchain": "SOL" "dstTokenAddress": "0x0000000000000000000000000000000000000000", "dstTokenBlockchain": "POLYGON", "referrer": "rubic.exchange", "fromAddress": "USER WALLET ADDRESS", "id": "ID FROM QUOTE STEP", "receiver": "RECEIVER ADDRESS" } }); const result = await response.json(); const { transaction } = result; console.log(transaction); // api/routes/swap always returns solana data in base64 format // { // "data": "AQAAAAAAAAAAA...SeOpIqnPIXvhm6MAcerlewmVsjBtvc2eDf4gKc2g==", // }, return result; } ``` You can get more information about swap endpoint here: [Request Data](https://dev-docs.rubic.exchange/docs/api-docs/request-data) ## Executing a Transaction with the API Response Data Using the data obtained from the Rubic API, you can now execute the transaction. ```javascript theme={null} import { base64 } from 'ethers/lib/utils'; import { VersionedTransaction } from '@solana/web3.js'; async function executeSwap( // Transaction object, obtained on previous step from Rubic API transaction, // Connection object connection ) { const decodedData = base64.decode(options.data) const tx = VersionedTransaction.deserialize(decodedData); const { blockhash } = await connection.getRecentBlockhash(); tx.message.recentBlockhash = blockhash; const { signature } = await window.solana.signAndSendTransaction(tx); console.log("Transaction executed:", tx.hash); } ``` ## Track your transaction Now you can track your transaction status **Endpoint:** `GET https://api-v2.rubic.exchange/api/routes/status` ```javascript theme={null} async function getStatus( // Your transaction hash, otained while executing transaction hash ) { const response = await fetch(`https://api-v2.rubic.exchange/api/info/status?srcTxHash=${hash}`); const data = await response.json(); const { status, destinationTxHash } = data; console.log(status); // Current TX status can be one of // 'PENDING' | 'LONG_PENDING' | 'REVERT' | // 'REVERTED' | 'FAIL' | 'READY_TO_CLAIM' | // 'SUCCESS' | 'NOT_FOUND'; console.log(status); // shows the hash on the target network if the transaction // is successfully completed return status; } ``` You can get more information about status endpoint here: [Get cross-chain status](https://dev-docs.rubic.exchange/docs/api-docs/get-crosschain-status) # Swaps from TON Source: https://docs.rubic.finance/docs/api-docs/integration-examples/swaps-from-ton This page explains how to connect a Web3 wallet, retrieve token quotes, approve tokens, and execute a transaction using Rubic API, with examples using TonConnectUI. ## Connecting a Web3 Wallet To interact with the blockchain, we first need to connect a wallet. Here are examples using `TonConnectUI.` ```javascript theme={null} import { TonConnectUI } from '@tonconnect/ui'; async function connectWallet() { const tonConnect = new TonConnectUI(...); try { await this.tonConnect.connector.restoreConnection(); } catch {} const isConnected = (await this.tonConnect.connectionRestored) && tonConnect.connected; if (!isConnected) { const payload = await RetroBridgeApiService.getMessageToAuthWallet(); this.tonConnect.setConnectRequestParameters({ state: 'ready', value: { tonProof: this.window.btoa(payload) } }); await this.openWalletModal(); } } ``` ## Retrieving Token Quotes Now that the wallet is connected, we can request token quotes from Rubic API. **Endpoint:** `POST https://api-v2.rubic.exchange/api/routes/quoteBest` ```javascript theme={null} async function quoteBest() { const response = await fetch("https://api-v2.rubic.exchange/api/routes/quoteBest", { method: "POST", headers: { "Content-Type": "application/json", }, body: { "srcTokenAddress": "0x0000000000000000000000000000000000000000", "srcTokenAmount": "10", "srcTokenBlockchain": "TON" "dstTokenAddress": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", "dstTokenBlockchain": "TON", "referrer": "rubic.exchange" } }); const data = await response.json(); const { estimate, transaction, id } = data; console.log(estimate); // { // This is an estimated amount you will get after the swap. // "destinationTokenAmount": "59.859216", // "destinationTokenMinAmount": "59.260624", // // "destinationUsdAmount": 59.86, // "destinationUsdMinAmount": 59.26, // // "destinationWeiAmount": "59859216", // "destinationWeiMinAmount": "59260624", // // "durationInMinutes": 5, // "priceImpact": 0.21, // "slippage": 0.01 // } console.log(id); // This is the swap ID. It will be needed later for swap request. return data; } ``` You can get more information about quote endpoint here: [Request Quote](https://dev-docs.rubic.exchange/docs/api-docs/request-quote) ## Retrieving Data to Execute a Transaction To perform a token swap through Rubic API, we need to get the necessary data for the transaction. **Endpoint:** `POST https://api-v2.rubic.exchange/api/routes/swap` ```javascript theme={null} async function getSwapData() { const response = await fetch("https://api-v2.rubic.exchange/api/routes/swap", { method: "POST", headers: { "Content-Type": "application/json", }, body: { "srcTokenAddress": "0x0000000000000000000000000000000000000000", "srcTokenAmount": "10", "srcTokenBlockchain": "TON" "dstTokenAddress": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", "dstTokenBlockchain": "TON", "referrer": "rubic.exchange" "fromAddress": "USER WALLET ADDRESS", "id": "ID FROM QUOTE STEP", "receiver": "RECEIVER ADDRESS" } }); const result = await response.json(); const { transaction } = result; console.log(transaction); // { // "tonMessages": [{ // "address": "0:1150b518b2626ad51899f98887f8824b70065456455f7fe2813f012699a4061f", // "amount": "10270000000", // "payload": "te6cckEBAgEAqgABbw+KfqUAA...VtY85yV2h5cGA/o2ZlxGelAhaWKht7fpKSyms=" // }] // } return result; } ``` You can get more information about swap endpoint here: [Request Data](https://dev-docs.rubic.exchange/docs/api-docs/request-data) ## Executing a Transaction with the API Response Data Using the data obtained from the Rubic API, you can now execute the transaction. ```javascript theme={null} import { base64 } from 'ethers/lib/utils'; import { VersionedTransaction } from '@solana/web3.js'; async function executeSwap( // Transaction object, obtained on previous step from Rubic API transaction, // Connection object tonConnect ) { const { boc } = await tonConnect.sendTransaction({ validUntil: Math.floor(Date.now() / 1000) + 360, messages: transaction.messages }); return boc; } ``` ## Track your transaction Now you can track your transaction status **Endpoint:** `GET https://api-v2.rubic.exchange/api/routes/status` ```javascript theme={null} async function getStatus( // Your transaction hash, otained while executing transaction hash ) { const response = await fetch(`https://api-v2.rubic.exchange/api/info/status?srcTxHash=${hash}`); const data = await response.json(); const { status, destinationTxHash } = data; console.log(status); // Current TX status can be one of // 'PENDING' | 'LONG_PENDING' | 'REVERT' | // 'REVERTED' | 'FAIL' | 'READY_TO_CLAIM' | // 'SUCCESS' | 'NOT_FOUND'; console.log(status); // shows the hash on the target network if the transaction // is successfully completed return status; } ``` You can get more information about status endpoint here: [Get cross-chain status](https://dev-docs.rubic.exchange/docs/api-docs/get-crosschain-status) # Swaps from Tron Source: https://docs.rubic.finance/docs/api-docs/integration-examples/swaps-from-tron This page explains how to connect a Web3 wallet, retrieve token quotes, approve tokens, and execute a transaction using Rubic API, with examples using ethers.js, web3.js, and viem. ## Connecting a Web3 Wallet To interact with the blockchain, we first need to connect a wallet. Here are examples using `tronWeb.` ```javascript theme={null} const TronWeb = require('tronweb'); async function connectWallet() { if (window.tronLink) { const response = await window.tronLink.request({ method: 'tron_requestAccounts' }); return window.tronLink.tronWeb.defaultAddress.base58; } else { console.error("Tron provider not found. Please install TronLink."); } } ``` ## Retrieving Token Quotes Now that the wallet is connected, we can request token quotes from Rubic API. **Endpoint:** `POST https://api-v2.rubic.exchange/api/routes/quoteBest` ```javascript theme={null} async function quoteBest() { const response = await fetch("https://api-v2.rubic.exchange/api/routes/quoteBest", { method: "POST", headers: { "Content-Type": "application/json", }, body: { "srcTokenAddress": "0x0000000000000000000000000000000000000000", "srcTokenAmount": "1000.05", "srcTokenBlockchain": "TRON", "dstTokenAddress": "0x0000000000000000000000000000000000000000", "dstTokenBlockchain": "ETH", "referrer": "rubic.exchange" } }); const data = await response.json(); const { estimate, transaction, id } = data; console.log(estimate); // { // This is an estimated amount you will get after the swap. // "destinationTokenAmount": "8248.453781656313882666", // "destinationTokenMinAmount": "8001.000168206624466186", // // "destinationUsdAmount": 2637.13, // "destinationUsdMinAmount": 2558.02, // // "destinationWeiAmount": "8248453781656313882666", // "destinationWeiMinAmount": "8001000168206624466186", // // "durationInMinutes": 5, // "priceImpact": 0.14, // "slippage": 0.03 // } console.log(transaction.approvalAddress); // This is the address you need to give approve to spend tokens. // See next section for details. // TMmBsvNipjm4VTqt5gydp72i7Facbzk1Ee console.log(id); // This is the swap ID. It will be needed later for swap request. return data; } ``` You can get more information about quote endpoint here: [Request Quote](https://dev-docs.rubic.exchange/docs/api-docs/request-quote) ## Approving Tokens for Transaction Before sending a transaction, you need to approve the token. `Approve` allows a user to authorize a contract or application to manage a specified amount of their tokens, which is necessary for secure interaction with decentralized applications such as exchanges or DeFi protocols. This gives users control over how many tokens can be used, providing an additional layer of security. Below are examples for different libraries. ```javascript theme={null} const tronWeb = require('tronweb'); import { TRC20_CONTRACT_ABI } from "./TokenABI"; // replace with the correct ABI async function approveToken( // Token address tokenAddress, // Contract to give approve to. // Put here transaction.approvalAddress obtained on previous step spenderAddress, // Amount of tokens to approve. // For security reasons it's better to set approve // amount equal to from amount amount ) { const contract = await tronWeb.contract(TRC20_CONTRACT_ABI, tokenAddress); const tx = await tokenContract.approve(spenderAddress, amount); console.log("Approval successful:", tx.hash); } ``` ## Retrieving Data to Execute a Transaction To perform a token swap through Rubic API, we need to get the necessary data for the transaction. **Endpoint:** `POST https://api-v2.rubic.exchange/api/routes/swap` ```javascript theme={null} async function getSwapData() { const response = await fetch("https://api-v2.rubic.exchange/api/routes/swap", { method: "POST", headers: { "Content-Type": "application/json", }, body: { "srcTokenAddress": "0x0000000000000000000000000000000000000000", "srcTokenAmount": "1000.05", "srcTokenBlockchain": "TRON", "dstTokenAddress": "0x0000000000000000000000000000000000000000", "dstTokenBlockchain": "ETH", "referrer": "rubic.exchange" "fromAddress": "USER WALLET ADDRESS", "id": "ID FROM QUOTE STEP", "receiver": "RECEIVER ADDRESS" } }); const result = await response.json(); const { transaction } = result; console.log(transaction); // EXAMPLE WITH RANDOM VALUES, don't supposed to be as a response for TRON->ETH swap // { // "approvalAddress": "TMmBsvNipjm4VTqt5gydp72i7Facbzk1Ee", // "arguments": [, , ...], // "signature": "06fdde03", // "to": "TMmBsvNipjm4VTqt5gydp72i7Facbzk1Ee", // "rawParameter"?: "0a020add22086c2763abadf9ed2940c8d5deea822e5a65080112610a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412300a15418840e6c55b9ada326d211d818c34a994aeced808121541d3136787e667d1e055d2cd5db4b5f6c880563049186470ac89dbea822e", // "callValue"?: "1138554300", // "feeLimit"?: 10000000000 // }, return result; } ``` You can get more information about swap endpoint here: [Request Data](https://dev-docs.rubic.exchange/docs/api-docs/request-data) ## Executing a Transaction with the API Response Data Using the data obtained from the Rubic API, you can now execute the transaction. ```javascript theme={null} async function executeSwap( // Signer object, obtained while ethers.js initializing tronWeb, // User wallet address fromAddress // Address of called contract contractAddress: string, // Method selector methodSignature: string, // tx arguments array parameters: Array<{type: string; value: string | TronParameters;}>, // tx options options: {feeLimit?: number; callValue?: string; rawParameter?: string;} ) { const tronTx = await tronWeb.transactionBuilder.triggerSmartContract( contractAddress, methodSignature, options, parameters, fromAddress ); const signedTransaction = await tronWeb.trx.sign(tronTx.transaction); const receipt: TronTransactionReceipt = await this.tronWeb.trx.sendRawTransaction( signedTransaction return receipt.txid; } ``` ## Track your transaction Now you can track your transaction status **Endpoint:** `GET https://api-v2.rubic.exchange/api/routes/status` ```javascript theme={null} async function getStatus( // Your transaction hash, otained while executing transaction hash ) { const response = await fetch(`https://api-v2.rubic.exchange/api/info/status?srcTxHash=${hash}`); const data = await response.json(); const { status, destinationTxHash } = data; console.log(status); // Current TX status can be one of // 'PENDING' | 'LONG_PENDING' | 'REVERT' | // 'REVERTED' | 'FAIL' | 'READY_TO_CLAIM' | // 'SUCCESS' | 'NOT_FOUND'; console.log(status); // shows the hash on the target network if the transaction // is successfully completed return status; } ``` You can get more information about status endpoint here: [Get cross-chain status](https://dev-docs.rubic.exchange/docs/api-docs/get-crosschain-status) # Swaps via Deposit Source: https://docs.rubic.finance/docs/api-docs/integration-examples/swaps-via-deposit This page explains how to execute a transaction via deposit using Rubic API. Swap via deposit does not require a wallet connection. User should make a deposit by himself. ## Retrieving Token Quotes Now that the wallet is connected, we can request token quotes from Rubic API. **Endpoint:** `POST https://api-v2.rubic.exchange/api/routes/quoteBest` ```javascript theme={null} async function quoteBest() { const response = await fetch("https://api-v2.rubic.exchange/api/routes/quoteBest", { method: "POST", headers: { "Content-Type": "application/json", }, body: { "srcTokenAddress": "0x0000000000000000000000000000000000000000", "srcTokenAmount": "3", "srcTokenBlockchain": "COSMOS", "dstTokenAddress": "0x0000000000000000000000000000000000000000", "dstTokenBlockchain": "TRON", "referrer": "rubic.exchange" } }); const data = await response.json(); const { estimate, transaction, id } = data; console.log(estimate); // { // This is an estimated amount you will get after the swap. // "destinationTokenAmount": "56.797373", // "destinationTokenMinAmount": "55.093452", // // "destinationUsdAmount": 13.26, // "destinationUsdMinAmount": 12.86, // // "destinationWeiAmount": "56797373", // "destinationWeiMinAmount": "55093452", // // "durationInMinutes": 5, // "priceImpact": 3.29, // "slippage": 0.03 // } console.log(id); // This is the swap ID. It will be needed later for swap request. return data; } ``` You can get more information about quote endpoint here: [Request Quote](https://dev-docs.rubic.exchange/docs/api-docs/request-quote) ## Retrieving Data to Execute a Transaction To perform a token swap through Rubic API, we need to get the necessary data for the transaction. **Endpoint:** `POST https://api-v2.rubic.exchange/api/routes/swap` ```javascript theme={null} async function getSwapData() { const response = await fetch("https://api-v2.rubic.exchange/api/routes/swap", { method: "POST", headers: { "Content-Type": "application/json", }, body: { "srcTokenAddress": "0x0000000000000000000000000000000000000000", "srcTokenAmount": "3", "srcTokenBlockchain": "COSMOS" "dstTokenAddress": "0x0000000000000000000000000000000000000000", "dstTokenBlockchain": "TRON", "referrer": "rubic.exchange", "fromAddress": "USER WALLET ADDRESS", "id": "ID FROM QUOTE STEP", "receiver": "RECEIVER ADDRESS" } }); const result = await response.json(); const { transaction } = result; console.log(transaction); // { // "depositAddress": "cosmos1hgp84me0lze8t4jfrwsr05aep2kr57zrk4gecx", // "amountToSend": "3" // "exchangeId": "jz4flw7ub37tr78b", // // "extraFields": { // can be null // "name": "Memo", // "value": "7799954959159693" // } // }, return result; } ``` You can get more information about swap endpoint here: [Request Data](https://dev-docs.rubic.exchange/docs/api-docs/request-data) ## Executing a Transaction with the API Response Data You should display the `depositAddress`, `amountToSend`, `exchangeId` and `extraFields` fields from the `transaction` object in your UI. The user should send amount to the received depositAddress from his wallet by himself. User should pass the extraFields.value field otherwise the transaction may fail. # Tokens API Source: https://docs.rubic.finance/docs/token-api/token-api This page is under development. We provide access to the Tokens API, available endpoints are presented here: [https://api-v2.rubic.exchange/api/swagger/#/Tokens/TokensController\_getStatus](https://api-v2.rubic.exchange/api/swagger/#/Tokens/TokensController_getStatus) # Error handling Source: https://docs.rubic.finance/error-handling ## RubicApiError All API-level errors thrown by the default HTTP client are wrapped into `RubicApiError`, a typed subclass of `Error`. You can find more information about error handling [here](https://docs.rubic.finance/api-docs/about/core-concepts/error-handling) ```typescript theme={null} import { RubicApiError } from '@cryptorubic/sdk-lite'; ``` ### Fields | Field | Type | Description | | --------- | --------------------- | ---------------------------------------------------------------------- | | `name` | `'RubicApiError'` | Always `'RubicApiError'` | | `message` | `string` | Same as `reason` — compatible with `Error.message` | | `code` | `number` | Numeric error code from the API | | `reason` | `string` | Human-readable error description | | `data` | `object \| undefined` | Extra context returned by the API (e.g. which field failed validation) | | `traceId` | `string \| undefined` | Internal request ID — include in bug reports | *** ## Catching errors ```typescript theme={null} import { SDK, RubicApiError } from '@cryptorubic/sdk-lite'; try { const quote = await sdk.quoteBest({ /* ... */ }); } catch (err) { if (err instanceof RubicApiError) { console.error(`[${err.code}] ${err.reason}`); // → '[1001] Insufficient liquidity for the requested amount' if (err.traceId) { console.error('Trace ID:', err.traceId); } } else { // Network error, timeout, etc. throw err; } } ``` *** ## Common error codes | Code | Reason | Typical cause | | ------ | -------------------------- | ------------------------------------------------------------- | | `1001` | Insufficient liquidity | Amount too large for the selected route | | `1002` | Minimum amount not reached | `srcTokenAmount` is below the provider minimum | | `1003` | Trade expired | The quote `id` has expired — re-quote and try again | | `1004` | Unsupported token pair | The token pair is not supported by any provider | | `1101` | Invalid `fromAddress` | Wallet address format is incorrect | | `1102` | Invalid `receiver` | Receiver address format is incorrect | | `1103` | Balance too low | Wallet doesn't have enough tokens | | `1104` | Insufficient gas | Wallet doesn't have enough native token for gas | | `2001` | Invalid blockchain | `srcTokenBlockchain` or `dstTokenBlockchain` is not supported | | `2002` | Invalid token address | Token address format is invalid for the given blockchain | > These codes are illustrative. Always check `err.reason` for the exact message from the API. *** ## Error patterns by method ### Quote expired — re-quote Quote IDs expire after a short period. If you get an expiry error on `swap`, re-run the quote: ```typescript theme={null} async function swapWithRetry(quoteParams, swapParams, maxRetries = 2) { for (let i = 0; i < maxRetries; i++) { try { const quote = await sdk.quoteBest(quoteParams); return await sdk.swap({ ...swapParams, id: quote.id }); } catch (err) { if (err instanceof RubicApiError && err.code === 1003 && i < maxRetries - 1) { console.warn('Trade expired, re-quoting...'); continue; } throw err; } } } ``` ### Minimum amount ```typescript theme={null} try { const quote = await sdk.quoteBest({ srcTokenAmount: '0.001', /* ... */ }); } catch (err) { if (err instanceof RubicApiError && err.code === 1002) { showError('Amount is too small. Please enter a larger amount.'); } } ``` ### Network / timeout errors ```typescript theme={null} try { const quote = await sdk.quoteBest({ /* ... */ }); } catch (err) { if (err instanceof RubicApiError) { // API returned an error response handleApiError(err); } else if (err.name === 'AbortError' || err.message?.includes('timeout')) { showError('Request timed out. Please try again.'); } else { showError('Network error. Check your connection.'); } } ``` *** ## Polling timeout `waitForStatus` rejects with a plain `Error('Polling timeout')` (not a `RubicApiError`) when the total timeout is exceeded: ```typescript theme={null} try { const status = await sdk.waitForStatus( { id: swapData.id, srcTxHash: tx.hash }, { timeout: 300_000 } ); } catch (err) { if (err instanceof Error && err.message === 'Polling timeout') { showError('Swap is taking longer than expected. Check the explorer for updates.'); } else if (err instanceof RubicApiError) { showError(`Status check failed: ${err.reason}`); } } ``` *** ## Custom HTTP client — error forwarding If you use a [custom HTTP client](./configuration#custom-http-client), you are responsible for parsing API errors. Use `RubicApiError.fromApiResponse` to convert the raw response body: ```typescript theme={null} import { RubicApiError } from '@cryptorubic/sdk-lite'; const myClient: HttpClient = { async post(url, body, options) { const res = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', ...options?.headers }, body: JSON.stringify(body), }); const data = await res.json(); if (!res.ok) { throw RubicApiError.fromApiResponse(data); } return data; }, // ... get }; ``` # Getting started Source: https://docs.rubic.finance/getting-started # Getting Started ## Installation ```bash theme={null} npm install @cryptorubic/sdk-lite # or yarn add @cryptorubic/sdk-lite # or pnpm add @cryptorubic/sdk-lite ``` `axios` is included as a dependency and used by default. If you prefer to bring your own HTTP client (e.g. `fetch`, `ky`, or a custom instance), see [Configuration → Custom HTTP client](./configuration#custom-http-client). *** ## Quick start The full flow of a cross-chain swap takes three steps: ``` quote → swap → sign & send ``` ### 1. Initialize the SDK ```typescript theme={null} import { SDK } from '@cryptorubic/sdk-lite'; const sdk = await SDK.create({ referrer: 'my-app', // identifies your integration apiKey: 'YOUR_API_KEY', // obtain at https://t.me/RubicPartnership }); ``` ### 2. Get the best quote ```typescript theme={null} const quote = await sdk.quoteBest({ srcTokenBlockchain: 'ETH', srcTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', // native ETH srcTokenAmount: '1', dstTokenBlockchain: 'POLYGON', dstTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', // native MATIC }); console.log('Provider:', quote.providerType); console.log('You receive:', quote.estimate.destinationTokenAmount, 'MATIC'); console.log('Trade ID:', quote.id); ``` ### 3. Get transaction data ```typescript theme={null} const swapData = await sdk.swap({ // reuse all quote params srcTokenBlockchain: 'ETH', srcTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', srcTokenAmount: '1', dstTokenBlockchain: 'POLYGON', dstTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', // required for swap id: quote.id, fromAddress: '0xYourWalletAddress', receiver: '0xDestinationAddress', }); // swapData.transaction contains: { to, data, value } // Send it with your wallet/web3 library: const tx = await signer.sendTransaction(swapData.transaction); ``` ### 4. Wait for completion ```typescript theme={null} const finalStatus = await sdk.waitForStatus( { id: swapData.id, srcTxHash: tx.hash }, { interval: 5000, onStatusUpdate: s => console.log('Status:', s.status), } ); if (finalStatus.status === 'SUCCESS') { console.log('Done! Destination tx:', finalStatus.destinationTxHash); } ``` *** ## One-call swap (swapBest) If you don't need to inspect the quote before sending, `swapBest` combines quoting and transaction building into a single request: ```typescript theme={null} const swapData = await sdk.swapBest({ srcTokenBlockchain: 'ETH', srcTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', srcTokenAmount: '1', dstTokenBlockchain: 'POLYGON', dstTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', fromAddress: '0xYourWalletAddress', receiver: '0xDestinationAddress', }); ``` *** ## Next steps * [Configuration](./configuration) — API key, integrator address, timeout, custom HTTP client * [Quoting Routes](./quote) — compare all available routes * [Executing Swaps](./swap) — swap, swapBest, deposit trades * [Tracking Status](./statuses) — poll until the transaction settles * [Error Handling](./error-handling) — handle `RubicApiError` # Info Source: https://docs.rubic.finance/info # Info Methods Info methods return metadata — supported blockchains, providers, and service health. *** ## getChains Returns a list of all blockchains supported by Rubic. ```typescript theme={null} const chains = await sdk.getChains(includeTestnets?: boolean): Promise ``` | Parameter | Type | Default | Description | | ----------------- | --------- | ------- | ------------------------------------------- | | `includeTestnets` | `boolean` | `false` | Include testnet blockchains in the response | ### Example ```typescript theme={null} const chains = await sdk.getChains(); chains.forEach(chain => { console.log(chain.name, chain.type, chain.id); }); // → 'ETH' 'evm' 1 // → 'BSC' 'evm' 56 // → 'SOLANA' 'solana' null // → ... ``` ### ChainInterface | Field | Type | Description | | ---------------- | ---------------- | --------------------------------------------------------------------- | | `name` | `BlockchainName` | Blockchain identifier used in all SDK requests | | `type` | `string` | Chain type: `'evm'`, `'solana'`, `'tron'`, `'ton'`, `'bitcoin'`, etc. | | `id` | `number \| null` | Chain ID (EVM only; `null` for non-EVM chains) | | `proxyAvailable` | `boolean` | Whether fee collection via Rubic proxy contracts is available | | `testnet` | `boolean` | Whether this is a testnet | ### Example — get EVM chains only ```typescript theme={null} const chains = await sdk.getChains(); const evmChains = chains.filter(c => c.type === 'evm' && !c.testnet); console.log('EVM mainnet chains:', evmChains.map(c => c.name)); ``` ### Example — with testnets ```typescript theme={null} const allChains = await sdk.getChains(true); const testnets = allChains.filter(c => c.testnet); console.log('Testnets:', testnets.map(c => c.name)); ``` *** ## getProviders Returns all available swap providers grouped by type. ```typescript theme={null} const providers = await sdk.getProviders(includeTestnets?: boolean): Promise ``` | Parameter | Type | Default | Description | | ----------------- | --------- | ------- | -------------------------------------------- | | `includeTestnets` | `boolean` | `false` | Include providers that only support testnets | ### Example ```typescript theme={null} const providers = await sdk.getProviders(); // Cross-chain providers (bridges, aggregators) providers.crossChain.forEach(p => { console.log(p.name, '→ supports', p.chains.length, 'chains'); }); // On-chain providers (DEXes) providers.onChain.forEach(p => { console.log(p.name, '→ supports', p.chains.length, 'chains'); }); ``` ### ProvidersInterface | Field | Type | Description | | ------------ | ------------------------------- | ------------------------------- | | `crossChain` | `CrossChainProviderInterface[]` | Bridge and aggregator providers | | `onChain` | `OnChainProviderInterface[]` | DEX providers | Each provider has: | Field | Type | Description | | -------- | -------------------------- | ----------------------------------------------------- | | `name` | `string` | Provider identifier (e.g. `'across'`, `'uniswap-v3'`) | | `chains` | `ProviderChainInterface[]` | Blockchains this provider supports | ### Example — check if a provider supports a chain pair ```typescript theme={null} const providers = await sdk.getProviders(); const across = providers.crossChain.find(p => p.name === 'across'); const supportsEth = across?.chains.some(c => c.from === 'ETH' && c.to === 'ARBITRUM'); console.log('Across supports ETH→ARB:', supportsEth); ``` *** ## healthcheck Checks whether the Rubic API is up and responsive. ```typescript theme={null} const result = await sdk.healthcheck(): Promise ``` Returns `'I am alive'` when the service is healthy. ```typescript theme={null} const health = await sdk.healthcheck(); // → 'I am alive' ``` # Configuration Source: https://docs.rubic.finance/mcp-docs/configuration ## **Quickstart** Add to MCP config: ```json theme={null} { "mcpServers": { "rubic": { "command": "npx", "args": ["-y", "@cryptorubic/mcp"], "env": { "EVM_WALLET_PRIVATE_KEY": "YOUR_PRIVATE_KEY" } } } } ``` `EVM_WALLET_PRIVATE_KEY` - EVM private key without `0x`. Enables signing/broadcast tools. ## **Local Installation Options** For read-only mode, omit `EVM_WALLET_PRIVATE_KEY`. ### **Option A: Node.js** Requires [Node.js v18+](https://nodejs.org/). ```text theme={null} git clone https://github.com/Cryptorubic/rubic-mcp.git cd rubic-mcp npm install npm run build ``` ### **Option B: Docker** Pull the published image: ```text theme={null} docker pull rubicfinance/rubic-mcp:latest ``` Or build from source: ```text theme={null} git clone https://github.com/Cryptorubic/rubic-mcp.git cd rubic-mcp docker build -t rubicfinance/rubic-mcp . ``` ## **Configuration** In case of local Node.js installation, copy the example config: ```text theme={null} cp .env.example .env ``` Main settings: * `EVM_WALLET_PRIVATE_KEY` - EVM private key without `0x`. Enables signing/broadcast tools. * `RUBIC_API_BASE_URL` - Rubic API base URL (default `https://rubic-api-v2.rubic.exchange`). * `TOKENS_API_BASE_URL` - Rubic tokens API base URL (default `https://api.rubic.exchange/api`). * `MCP_TRANSPORT` - `stdio` (default) or `http`. * `MCP_HOST` / `MCP_PORT` - used in HTTP mode. * `API_TIMEOUT_MS` / `MCP_TOOL_TIMEOUT_MS` - request and tool execution timeouts. Without `EVM_WALLET_PRIVATE_KEY`, read-only and build tools work, but tools that sign transactions will return an error. ## **Connecting to MCP Clients** [Quickstart](/mcp-docs/configuration#quickstart) section is enough for the most use cases. All of the instructions below are related to local installation options. All examples below use **stdio** mode. Replace `/full/path/to` with the actual path printed after `npm run build`. **Claude Code** ```text theme={null} # With private key claude mcp add rubic -e EVM_WALLET_PRIVATE_KEY=YOUR_PRIVATE_KEY -- node /full/path/to/dist/index.js # Read-only / unsigned mode claude mcp add rubic -- node /full/path/to/dist/index.js ``` Using Docker: ```text theme={null} claude mcp add rubic -e EVM_WALLET_PRIVATE_KEY=YOUR_PRIVATE_KEY -- docker run -i --rm rubicfinance/rubic-mcp:latest node dist/index.js ``` Verify: `claude mcp list` **Claude Desktop** Add to `claude_desktop_config.json`: Node.js: ```json theme={null} { "mcpServers": { "rubic": { "command": "node", "args": ["/full/path/to/dist/index.js"], "env": { "EVM_WALLET_PRIVATE_KEY": "YOUR_KEY" } } } } ``` Docker: ```json theme={null} { "mcpServers": { "rubic": { "command": "docker", "args": ["run", "-i", "--rm", "-e", "EVM_WALLET_PRIVATE_KEY=YOUR_KEY", "rubicfinance/rubic-mcp", "node", "dist/index.js"], "env": {} } } } ``` **Cursor** Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global): ```json theme={null} { "mcpServers": { "rubic": { "command": "node", "args": ["/full/path/to/dist/index.js"], "env": { "EVM_WALLET_PRIVATE_KEY": "YOUR_PRIVATE_KEY" } } } } ``` **Windsurf** Add to `~/.codeium/windsurf/mcp_config.json`: ```json theme={null} { "mcpServers": { "rubic": { "command": "node", "args": ["/full/path/to/dist/index.js"], "env": { "EVM_WALLET_PRIVATE_KEY": "YOUR_KEY" } } } } ``` **GitHub Copilot (VS Code)** Add to `.vscode/mcp.json`: ```json theme={null} { "mcpServers": { "rubic": { "type": "stdio", "command": "node", "args": ["/full/path/to/dist/index.js"], "env": { "EVM_WALLET_PRIVATE_KEY": "YOUR_KEY" } } } } ``` **Cline** Open Cline settings → MCP Servers → Edit MCP Settings: ```json theme={null} { "mcpServers": { "rubic": { "command": "node", "args": ["/full/path/to/dist/index.js"], "env": { "EVM_WALLET_PRIVATE_KEY": "YOUR_KEY" } } } } ``` **Continue** Add to `~/.continue/config.json`: ```json theme={null} { "mcpServers": [ { "name": "rubic", "command": "node", "args": ["/full/path/to/dist/index.js"], "env": { "EVM_WALLET_PRIVATE_KEY": "YOUR_KEY" } } ] } ``` **Zed** Add to `~/.config/zed/settings.json`: ```json theme={null} { "context_servers": { "rubic": { "command": { "path": "node", "args": ["/full/path/to/dist/index.js"], "env": { "EVM_WALLET_PRIVATE_KEY": "YOUR_KEY" } } } } } ``` ### **Other clients (generic stdio)** Use command `node` + args `["/full/path/to/dist/index.js"]`, or Docker command: ```text theme={null} docker run -i --rm -e EVM_WALLET_PRIVATE_KEY=YOUR_PRIVATE_KEY rubicfinance/rubic-mcp:latest node dist/index.js ``` ## **Hosted MCP** Use hosted read-only MCP endpoint: `https://mcp-api-v2.rubic.exchange/mcp` Example generic MCP config: ```json theme={null} { "mcpServers": { "rubic": { "url": "https://mcp-api-v2.rubic.exchange/mcp" } } } ``` ## **Transport modes** ### **Node.js** ```text theme={null} # stdio (default) npm start # HTTP mode MCP_TRANSPORT=http npm run start:http ``` ### **Docker** ```text theme={null} # stdio docker run -i --rm -e EVM_WALLET_PRIVATE_KEY=YOUR_PRIVATE_KEY rubicfinance/rubic-mcp:latest node dist/index.js # HTTP mode docker run -d -p 3333:3333 -e MCP_TRANSPORT=http rubicfinance/rubic-mcp:latest ``` Or with Docker Compose: ```text theme={null} docker compose up -d --build ``` ## **Development** ```text theme={null} npm run dev # stdio dev mode npm run dev:http # HTTP dev mode npm run lint npm run typecheck ``` # Examples Source: https://docs.rubic.finance/mcp-docs/examples ## **Get Token Details** > Get USDC token info on Ethereum **Response:** ```json theme={null} { "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "decimals": 6, "symbol": "USDC", "name": "USD Coin", "blockchain": "ETH", "price": 0.999646 } ``` ## On-Chain Swap Quote > Get a quote to swap 0.1 ETH to USDC on Arbitrum **Response:** ```json theme={null} { "mode": "best", "result": { "estimate": { "destinationTokenAmount": "207.74483", "destinationTokenMinAmount": "205.667382", "destinationUsdAmount": 207.68, "destinationUsdMinAmount": 205.6, "durationInMinutes": 1, "priceImpact": 0.06 }, "fees": { "gasTokenFees": { // gas fee info }, "percentFees": { // rubic's fee info } }, "providerType": "ODOS", "routing": [ { "path": [ { "address": "0x0000000000000000000000000000000000000000", "amount": "0.1", "blockchain": "ARBITRUM", "blockchainId": 42161, "decimals": 18, "name": "ETH", "symbol": "ETH", "price": 2077.93 }, { "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "amount": "207.74483", "blockchain": "ARBITRUM", "blockchainId": 42161, "decimals": 6, "name": "USD Coin", "symbol": "USDC", "price": 1 } ], "provider": "ODOS", "type": "on-chain" } ], "swapType": "on-chain", "tokens": { // tokens' info }, "transaction": { "approvalAddress": "0x3335733c454805df6a77f825f266e136FB4a3333" }, "warnings": [], "id": // rubic's id } } ``` In case your `EVM_PRIVATE_WALLET_KEY` is configured, agent will be able to execute transaction. Otherwise, you will receive Rubic's url to swap in browser. ## Cross-Chain Swap Quote > Bridge 500 USDC from Ethereum to Arbitrum **Response:** ```json theme={null} { "mode": "best", "result": { "estimate": { "destinationTokenAmount": "497.979727", "destinationTokenMinAmount": "483.040335", "destinationUsdAmount": 497.79, "destinationUsdMinAmount": 482.86, "durationInMinutes": 1, "priceImpact": null }, "fees": { "gasTokenFees": { // gas fee info }, "percentFees": { // rubic's fee info } }, "providerType": "squidrouter", "routing": [ { "path": [ { "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "amount": "498", "blockchain": "ETH", "blockchainId": 1, "decimals": 6, "name": "USD Coin", "symbol": "USDC", "price": 1 }, { "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "amount": "497.979727", "blockchain": "ARBITRUM", "blockchainId": 42161, "decimals": 6, "name": "USD Coin", "symbol": "USDC", "price": 1 } ], "provider": "squidrouter", "type": "cross-chain" } ], "swapType": "cross-chain", "tokens": { // tokens' info }, "transaction": { "approvalAddress": "0x3335733c454805df6a77f825f266e136FB4a3333" }, "warnings": [], "id": // rubic's id } } ``` In case your `EVM_PRIVATE_WALLET_KEY` is configured, agent will be able to execute transaction. Otherwise, you will receive Rubic's url to swap in browser. ## Swap Simulation > Simulate swapping 50 TRX to SOL **Response:** ```json theme={null} { "swap": { "estimate": { "destinationTokenAmount": "0.220675833", "destinationTokenMinAmount": "0.214055558", "destinationUsdAmount": 18.44, "destinationUsdMinAmount": 17.89, "durationInMinutes": 1, "priceImpact": 1.31, }, "fees": { "gasTokenFees": { // gas fee info }, "percentFees": { // rubic's fee info } }, "providerType": "near_intents", "routing": [ { "path": [ { "address": "0x0000000000000000000000000000000000000000", "amount": "50", "blockchain": "TRON", "blockchainId": 195, "decimals": 6, "name": "TRX", "symbol": "TRX", "price": 0.37 }, { "address": "So11111111111111111111111111111111111111111", "amount": "0.220675833", "blockchain": "SOLANA", "blockchainId": 7565164, "decimals": 9, "name": "Solana", "symbol": "SOL", "price": 83.58 } ], "provider": "near_intents", "type": "cross-chain" } ], "swapType": "cross-chain", "tokens": { // tokens' info }, "transaction": { "depositAddress": "TGvLb21GVMXdKoWDdRJA5TbXrGdKaMdBXL", "amountToSend": "50", "exchangeId": "TGvLb21GVMXdKoWDdRJA5TbXrGdKaMdBXL" }, "useRubicContract": false, "warnings": [] }, "summary": { "durationInMinutes": 1, "estimatedGasUsd": null, "expectedOutputAmount": "0.220675833", "expectedOutputMinAmount": "0.214055558", "expectedOutputUsd": 18.44, "priceImpact": 1.31, "reasons": [ "Price impact is elevated (>= 15%)." ], "riskLevel": "high", "slippage": 0.03, "totalCostUsd": 0, "routeId": // rubic's id } } ``` ## Portfolio and Balance Checks > Check my balances across supported chains **Response:** ```json theme={null} { "address": /* your wallet address */, "balances": [ { "blockchain": "AVALANCHE", "tokens": [ { "address": "", "balance": "0.099987509909665979", "decimals": 18, "name": "Avalanche", "symbol": "AVAX" }, { "address": "0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e", "balance": "1.8", "decimals": 6, "name": "Circle USD", "symbol": "USDC" } ] }, { "blockchain": "ZK_SYNC", "tokens": [ { "address": "", "balance": "0.0010359777915", "decimals": 18, "name": "Ether", "symbol": "ETH" }, { "address": "0x493257fd37edb34451f62edf8d2a0c418852ba4c", "balance": "5.097301", "decimals": 6, "name": "Tether USD", "symbol": "USDT" } ] } ], "summary": "Found 4 tokens with non-zero balance across 2 chains" } ``` ## Browser Fallback > Open this swap route in Rubic **Response:** ```json theme={null} { "data": "https://app.rubic.exchange/?fromChain=ARBITRUM&from=ETH&to=USDC&toChain=ARBITRUM&amount=0.1" } ``` # Overview Source: https://docs.rubic.finance/mcp-docs/overview A Model Context Protocol (MCP) server for Rubic that enables AI agents to search supported chains/tokens, build swap transactions, sign and broadcast EVM transactions, track cross-chain status, and generate pre-filled swap URLs. Github repository: [https://github.com/Cryptorubic/rubic-mcp](https://github.com/Cryptorubic/rubic-mcp) ## **Quickstart** Requires [Node.js v18+](https://nodejs.org/) installed locally (used by `npx`). Add to MCP config: ```json theme={null} { "mcpServers": { "rubic": { "command": "npx", "args": ["-y", "@cryptorubic/mcp"], "env": { "EVM_WALLET_PRIVATE_KEY": "YOUR_PRIVATE_KEY" } } } } ``` `EVM_WALLET_PRIVATE_KEY` - EVM private key without `0x`. Enables signing/broadcast tools. ## **Example Workflow** A typical cross-chain swap via the MCP server follows this flow: ```text theme={null} 1. rubic_get_supported_chains # List supported chains 2. rubic_search_tokens # Get token addresses 3. rubic_quote_routes # Get best route 4. rubic_simulate_swap (optional) # Simulate transaction 5. rubic_build_swap_tx # Build swap transaction 6. rubic_sign_and_broadcast_tx # Execute transaction 7. rubic_track_status # Track cross-chain progress ``` ## **Tools** Tools are split into **read-only** (work without a key) and **execution** (require `EVM_WALLET_PRIVATE_KEY`). In [hosted mode](/mcp-docs/configuration#hosted-mcp), only read-only tools are available. | **Tool** | **Requires**`EVM_WALLET_PRIVATE_KEY` | **Description** | | :--------------------------------------- | :----------------------------------- | :----------------------------------------------------------------------------------------------------- | | `rubic_get_instructions` | - | Returns Rubic MCP usage guide and workflow tips | | `rubic_get_balances` | - | Returns non-zero native and ERC-20 balances across supported EVM chains | | `rubic_get_supported_chains` | - | Lists supported blockchain names | | `rubic_search_tokens` | - | Searches tokens by symbol, name, or address | | `rubic_quote_routes` | - | Calculates best route or all routes | | `rubic_simulate_swap` | - | Simulates execution preview (route, fees summary, gas USD, risk level) without signing or broadcasting | | `rubic_build_swap_tx` | - | Builds executable swap transaction payload | | `rubic_sign_tx` | Yes | Signs EVM transaction payload | | `rubic_broadcast_tx` | - | Broadcasts a signed raw transaction | | `rubic_sign_and_broadcast_tx` | Yes | Signs and broadcasts in one call | | `rubic_quote_swap_sign_and_broadcast_tx` | Yes | Full flow: quote -> build -> sign -> broadcast | | `rubic_track_status` | - | Tracks cross-chain status by route id and/or tx hash | | `rubic_get_swap_url` | - | Generates pre-filled Rubic app swap URL | ## **Security Model** Rubic MCP Server is non-custodial: * **Private keys never leave your machine.** `EVM_WALLET_PRIVATE_KEY` is read from a local `.env` file or MCP client config, used for in-process signing via [viem](https://viem.sh/), and never transmitted over the network. * **The server constructs transaction calldata** (`rubic_build_swap_tx`) and returns it as a structured JSON object. Signing and broadcast are separate, opt-in steps. * **Without** `EVM_WALLET_PRIVATE_KEY`, the server operates in read-only mode: quotes, token search, chain discovery, and swap URL generation work normally. Signing tools return a clear error. * **The Rubic API** (`rubic-api-v2.rubic.exchange`) receives swap parameters and returns routing + calldata. It never receives your private key. ## **Limitations** Rubic MCP Server does **not**: * **Custody or store private keys.** Keys exist only in your local env / process memory. * **Support non-EVM chains for signing.** `rubic_sign_tx` and `rubic_broadcast_tx` work only on EVM chains. For non-EVM chains (Solana, TRON, TON, Bitcoin), use `rubic_build_swap_tx` to get calldata and sign externally, or use `rubic_get_swap_url` for browser-based execution. * **Execute limit orders or DCA.** Only market swaps via routing aggregation. * **Guarantee complete portfolio coverage.** `rubic_get_balances` checks tokens from bundled `tokens.json`. Custom/unlisted tokens may require manual contract checks. * **Manage token approvals automatically.** If an ERC-20 approval is needed, `rubic_build_swap_tx` returns `approvalAddress` — the user must approve separately. * **Guarantee price.** Quotes are estimates; actual execution price may differ due to slippage, MEV, or market movement between quote and broadcast. * **Support fiat on/off-ramp.** No bank, card, or payment provider integration. ## **Response format** All tools return a stable result envelope: ```json theme={null} { "ok": true, "traceId": "uuid", "data": {}, "error": { "code": "RUBIC_1001", "message": "Human-readable reason", "statusCode": 400, "details": {} } } ``` ## **Error Codes** | **Code** | **Meaning** | | :---------------------- | :---------------------------------------------------------- | | `QUOTE_ROUTES_FAILED` | Rubic API could not calculate any route for the given pair | | `ROUTE_ID_NOT_FOUND` | Route id could not be extracted from quote response | | `BUILD_SWAP_TX_FAILED` | Transaction construction failed for the selected route | | `SIGN_TX_FAILED` | Transaction signing failed (key mismatch, invalid tx) | | `BROADCAST_TX_FAILED` | Signed transaction rejected by the network | | `WALLET_NOT_CONFIGURED` | Tool requires EVM\_WALLET\_PRIVATE\_KEY but it is not set | | `TOOL_TIMEOUT` | Tool execution exceeded configured timeout | | `HTTP_400` | Input validation failed | | `HTTP_NETWORK` | Network request to Rubic API failed | | `RUBIC_` | Rubic API business error (code forwarded from API response) | | `INTERNAL_ERROR` | Unexpected server error | # Overview Source: https://docs.rubic.finance/overview # Rubic SDK — Overview Rubic SDK is a lightweight TypeScript wrapper around the [Rubic API](https://docs.rubic.finance/api-docs/about/overview). It provides a typed, ergonomic interface for integrating cross-chain and on-chain token swaps into any JavaScript or TypeScript application. ## What it covers * **Quoting** — get all routes or the best route for a swap * **Swapping** — get transaction data ready to sign and send * **Deposit trades** — routes that don't require a source wallet (send funds to a deposit address) * **Status tracking** — poll transaction status until it settles, with a built-in `waitForStatus` helper * **Utility** — allowance, approve, claim, refund, wallet auth * **Info** — supported chains and providers ## Architecture ``` Your App │ ▼ SDK.create({ referrer, apiKey, ... }) │ ├── routes/ quoteAll · quoteBest · quoteDepositTrades │ swap · swapBest · swapDepositTrade │ ├── info/ getChains · getProviders · getStatusExtended │ waitForStatus (polling helper) │ └── utility/ allowance · checkApprove · claim celerRefund · authWalletMessage · healthcheck ``` ## Supported swap types | Type | Description | | ------------------ | ------------------------------------------------------------------------------------------ | | **Cross-chain** | Swap tokens across different blockchains via bridges | | **On-chain** | Swap tokens within the same blockchain via DEXes | | **Deposit trades** | Cross-chain swaps where you send funds to a deposit address (no wallet required on source) | ## Pages * [Getting Started](./getting-started) * [Configuration](./configuration) * [Quoting Routes](./quote) * [Executing Swaps](./swap) * [Tracking Status](./statuses) * [Info Methods](./info) * [Utility Methods](./utility) * [Error Handling](./error-handling) # Quote Source: https://docs.rubic.finance/quote # Quoting Routes Quoting calculates available swap routes **without executing anything on-chain**. Use quotes to show users their options before they confirm a transaction. *** ## Common request parameters All quote methods accept these base fields: | Field | Type | Description | | -------------------- | ---------------- | ---------------------------------------------------------------------------------- | | `srcTokenBlockchain` | `BlockchainName` | Source blockchain (e.g. `'ETH'`, `'BSC'`, `'POLYGON'`) | | `srcTokenAddress` | `string` | Token address on the source chain. Use `0xEeee...EEeE` for native tokens | | `srcTokenAmount` | `string` | Amount to swap in token units (not wei) | | `dstTokenBlockchain` | `BlockchainName` | Destination blockchain | | `dstTokenAddress` | `string` | Token address on the destination chain | | `fromAddress` | `string` | *(optional)* Sender wallet address. Required by some providers for accurate quotes | | `receiver` | `string` | *(optional)* Recipient address on the destination chain | | `slippage` | `number` | *(optional)* Max slippage in percent (e.g. `1` = 1%) | | `integratorAddress` | `string` | *(optional)* Overrides the SDK-level integrator address for this request | | `preferredProvider` | `string` | *(optional)* Force a specific provider | | `enableChecks` | `boolean` | *(optional)* Enable balance/gas checks. Default: `true` | | `showFailedRoutes` | `boolean` | *(optional)* Include failed routes in `quoteAll` response. Default: `false` | *** ## quoteBest Returns the single route with the highest expected output. ```typescript theme={null} const quote = await sdk.quoteBest(params: QuoteRequestInterface): Promise ``` ### Example ```typescript theme={null} const quote = await sdk.quoteBest({ srcTokenBlockchain: 'ETH', srcTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', srcTokenAmount: '1', dstTokenBlockchain: 'BSC', dstTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', }); console.log(quote.id); // → 'uuid-...' console.log(quote.providerType); // → 'across' console.log(quote.swapType); // → 'cross-chain' console.log(quote.estimate.destinationTokenAmount); // → '0.412' console.log(quote.estimate.destinationTokenMinAmount); // → '0.408' console.log(quote.estimate.durationInMinutes); // → 3 console.log(quote.estimate.slippage); // → 1 ``` ### Response: QuoteResponseInterface | Field | Type | Description | | ------------------------------------ | ----------------------------- | ---------------------------------------------------- | | `id` | `string` | Trade identifier — pass this to `swap()` | | `providerType` | `string` | Bridge or DEX used (e.g. `'across'`, `'uniswap-v3'`) | | `swapType` | `'cross-chain' \| 'on-chain'` | Type of the swap | | `tokens.from` | `TokenInterface` | Source token info + amount | | `tokens.to` | `TokenInterface` | Destination token info + expected amount | | `estimate.destinationTokenAmount` | `string` | Expected output in token units | | `estimate.destinationTokenMinAmount` | `string` | Minimum output after slippage | | `estimate.durationInMinutes` | `number` | Estimated completion time | | `estimate.priceImpact` | `number \| null` | Price impact in percent | | `fees.gasTokenFees` | `object` | Gas fee breakdown | | `fees.percentFees` | `object` | Protocol and integrator fee breakdown | | `routing` | `RoutingInterface[]` | Step-by-step route path | | `warnings` | `ErrorInterface[]` | Non-fatal provider warnings | | `useRubicContract` | `boolean` | Whether the swap goes through Rubic proxy contracts | *** ## quoteAll Returns **all available routes**, sorted by expected output (best first). ```typescript theme={null} const result = await sdk.quoteAll(params: QuoteRequestInterface): Promise ``` ### Example ```typescript theme={null} const result = await sdk.quoteAll({ srcTokenBlockchain: 'ETH', srcTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC srcTokenAmount: '1000', dstTokenBlockchain: 'POLYGON', dstTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174', // USDC showFailedRoutes: true, }); // Best route const best = result.routes[0]; console.log(best.providerType, best.estimate.destinationTokenAmount); // All routes result.routes.forEach(route => { console.log(route.providerType, '→', route.estimate.destinationTokenAmount); }); // Failed routes (when showFailedRoutes: true) result.failed?.forEach(fail => { console.log(fail.providerType, 'failed:', fail.data.reason); }); ``` ### Response: QuoteAllInterface | Field | Type | Description | | -------- | -------------------------- | ------------------------------------------------ | | `quote` | `QuoteRequestInterface` | Echo of the original request | | `routes` | `QuoteResponseInterface[]` | Successful routes, sorted best-first | | `failed` | `FailedQuoteInterface[]` | Failed routes (only if `showFailedRoutes: true`) | *** ## quoteDepositTrades Returns routes where the user **sends funds directly to a deposit address** — no on-chain transaction is required from the source wallet. Useful for CEXes, hardware wallets, or any scenario where the user can't sign a transaction. ```typescript theme={null} const result = await sdk.quoteDepositTrades(params): Promise ``` > The request is the same as `quoteAll` but `fromAddress` is optional and the response only contains deposit-based providers (e.g. ChangeNOW, Exolix, SimpleSwap). ### Example ```typescript theme={null} const result = await sdk.quoteDepositTrades({ srcTokenBlockchain: 'BTC', srcTokenAddress: '0x0000000000000000000000000000000000000000', srcTokenAmount: '0.1', dstTokenBlockchain: 'ETH', dstTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', receiver: '0xYourEthereumAddress', }); const route = result.routes[0]; console.log('Provider:', route.providerType); console.log('You receive:', route.estimate.destinationTokenAmount, 'ETH'); ``` *** ## Comparing providers ```typescript theme={null} const result = await sdk.quoteAll({ /* params */ }); const comparison = result.routes.map(r => ({ provider: r.providerType, receive: r.estimate.destinationTokenAmount, minReceive: r.estimate.destinationTokenMinAmount, estimatedTime: r.estimate.durationInMinutes + ' min', priceImpact: r.estimate.priceImpact + '%', })); console.table(comparison); ``` *** ## Next step Once you have a quote and its `id`, pass it to [`sdk.swap()`](./swap) to get transaction data. # Rubic SDK Source: https://docs.rubic.finance/rubic-sdk SDK is currently being updated. Detailed information will be added later. Please stay tuned! In the meantime, we recommend considering [API integration](https://dev-docs.rubic.exchange/api-docs/about/overview). For any questions regarding the API or SDK, please contact our [Business Development team](https://t.me/RubicPartnership). # MixBytes Audit Source: https://docs.rubic.finance/rubic/audits/audits Here's the final audit report by [MixBytes](https://mixbytes.io/)! All findings have been addressed, fixed or acknowledged by the Rubic Development team. **Check out the full audit report here:** [**https://github.com/mixbytes/audits\_public/blob/master/Rubic/Rubic%20Security%20Audit%20Report.pdf**](https://github.com/mixbytes/audits_public/blob/master/Rubic/Rubic%20Security%20Audit%20Report.pdf) # Stellar Audit Source: https://docs.rubic.finance/rubic/audits/stellar-audit Here's the final audit report by Stellar. All findings have been addressed, fixed or acknowledged by the Rubic Development team. **Check out the full audit report here:** [https://drive.google.com/file/d/1opOuoh0ozdfHuofL6TnVEiHeyk16TsQD/view?usp=sharing](https://drive.google.com/file/d/1opOuoh0ozdfHuofL6TnVEiHeyk16TsQD/view?usp=sharing) # Business Development Source: https://docs.rubic.finance/rubic/contacts/business-development For partnership inquiries, including service utilization and promotional opportunities, please contact our Business Development Team via [Telegram](https://t.me/RubicPartnership). # PR and Marketing Source: https://docs.rubic.finance/rubic/contacts/pr-marketing Are you up for collaboration and cross-marketing? Let us know! Diana Kuznetsova: [**kuznetsova.diana@rubic.finance**](mailto:kuznetsova.diana@rubic.finance) Dannie Hristov: [**dannie.hristov@rubic.finance**](mailto:dannie.hristov@rubic.finance) # Support Source: https://docs.rubic.finance/rubic/contacts/support Our Support Team is always happy to help you with any questions related to the Rubic platform. You can reach out to our team through several communication channels: 1. Telegram Support Bot:[ https://t.me/RubicSupportBot](https://t.me/RubicSupportBot) 2. Discord ticket system:[ https://discord.gg/7EYzPbWKFQ](https://discord.gg/7EYzPbWKFQ) 3. Website LiveChat widget on[ ](https://rubic.exchange/%E2%80%8B%E2%80%8B%E2%80%8B%E2%80%8B%E2%80%8B%E2%80%8B%E2%80%8B)[https://rubic.exchange/](https://rubic.exchange/) or [https://app.rubic.exchange/](https://app.rubic.exchange/) The Founders / Team Members / Support Team and Moderators will never PM/DM first!\ \ No one from the Rubic team will ever ask you for money, wallet private keys, to open a link or to provide your personal information.\ \ Always verify the source of the information! When in doubt, ask for help in our official channels.\ \ Rubic will ONLY post official announcements on [Discord](https://discord.com/invite/7EYzPbWKFQ) in #📢announcements, on [Telegram](https://t.me/cryptorubic), [X](https://x.com/CryptoRubic), [LinkedIn](https://www.linkedin.com/company/cryptorubic/), [Reddit](https://www.reddit.com/r/Rubic/), [Warpcast](https://farcaster.xyz/cryptorubic), and on our [blog](https://rubic.exchange/blog/). # Privacy Policy Source: https://docs.rubic.finance/rubic/legal-documentation/privacy-policy **Please review our Privacy Policy here:** [**https://rubic.exchange/pdf/privacy-policy.pdf**](https://rubic.exchange/pdf/privacy-policy.pdf) # Terms of Use Source: https://docs.rubic.finance/rubic/legal-documentation/terms-of-use **Please review our Terms of Use here:** [**https://rubic.exchange/pdf/terms-of-use.pdf**](https://rubic.exchange/pdf/terms-of-use.pdf) # B2B Cross-Chain Toolkit Source: https://docs.rubic.finance/rubic/overview/b2b-tools Rubic provides the tools for crypto projects to become fully interoperable across blockchains, with a fully customizable API and SDK Apipoints [**Contact Business Development team**](https://t.me/RubicPartnership) ## Use cases | Integrator | Links | Dev Tool | | :-------------- | :--------------------------------------------------------------- | :------- | | PortalX | [https://portalxswap.io/](https://portalxswap.io/) | SDK | | Best Wallet | [https://bestwallet.com/en](https://bestwallet.com/en) | API | | D'Cent | [https://www.dcentwallet.com/en](https://www.dcentwallet.com/en) | API | | HoldStation | [https://holdstation.com/](https://holdstation.com/) | API | | DODO | [https://dodoex.io/en](https://dodoex.io/en) | API | | NFA Trading Bot | [https://x.com/nfa\_club](https://x.com/nfa_club) | API | | Clear Swap | [https://clearswap.io/](https://clearswap.io/) | API | | Blum | [https://www.blum.io/](https://www.blum.io/) | API | | Exolix | [https://exolix.com/](https://exolix.com/) | API | | Radr | [https://www.radrlabs.io/](https://www.radrlabs.io/) | API | | Swapzone | [https://swapzone.io/](https://swapzone.io/) | API | | BazaarSwap | [https://www.bazaarswap.io/](https://www.bazaarswap.io/) | API | | Sumex | [https://sumex.io/](https://sumex.io/) | API | | CrossCurve | [https://crosscurve.fi/](https://crosscurve.fi/) | API | | Palindrome Pay | [https://www.palindromepay.com](https://www.palindromepay.com) | API | | Quickex | [https://quickex.io](https://quickex.io) | API | | LinkiSwap | [https://www.linkiswap.com](https://www.linkiswap.com) | API | | TonX | [https://tonx.trade/](https://tonx.trade/) | API | | Magno | [www.magno.fi](http://www.magno.fi) | API | # Rubic's Ecosystem Source: https://docs.rubic.finance/rubic/overview/ecosystem Welcome to the Rubic ecosystem, where we shape the future of Web3 cross-chain technology. Our mission is to make it seamless for developers and users to harness the vast potential of multiple blockchain networks, assets, and dApps. Rubic never stands still, adding new blockchains, bridges, DEXs and intent-protocols to improve cross-chain and on-chain swapping performance, offering the best routes, and saving you time and money. No need to roam around Web3 checking different providers - Rubic is your ultimate cross-chain destination! ## **Supported Chains** Discover the diverse array of blockchain networks that Rubic seamlessly integrates into its ecosystem. With over 70 supported chains, we provide access to a vast spectrum of decentralized technologies, ensuring that your cross-chain journey knows no bounds. Explore the potential of major blockchains, all under the Rubic umbrella. | Status | Network | DEXs | | :----- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ✅ | Ethereum | 1Inch
Li.Fi
OpenOcean
Odos
Uniswap V2, V3
Native Router
Rango
Verse
SushiSwap | | ✅ | BNB Chain | Native Router
Odos
OpenOcean
iZUMi
Squid
Uniswap V2, V3
Verse
SushiSwap
Rango
1Inch
Li.Fi | | ✅ | Polygon | Native Router
Odos
OpenOcean
QuickSwap, V3
Squid
Uniswap V2, V3
Verse
SushiSwap
Rango
1Inch
Li.Fi | | ✅ | Avalanche | Joe
Squid Router
Pangolin
OpenOcean
Odos
NativeRouter
Uniswap V2, V3
Verse
Rango
Pangolin
1Inch
Li.Fi
SushiSwap | | ✅ | Fantom | SpookySwap
SoulSwap
OpenOcean
NativeSwap
Uniswap V2, V3
Li.Fi
1inch
Rango
SushiSwap
Verse
Odos | | ✅ | Arbitrum | Native Router
Odos
OpenOcean
Squid
Uniswap V2, V3
Verse
SushiSwap
Rango
1Inch
Li.Fi
Camelot | | ✅ | Solana | Jupiter
Squid
DeBridge
DFlow
Li.Fi
Raydium
OpenOcean
Orca | | ✅ | Optimism | Odos
OpenOcean
Li.Fi
Squid
1Inch
Rango | | ✅ | Bitcoin | - | | ✅ | Tron | - | | ✅ | Kava Cosmos | - | | ✅ | Metis | OpenOcean
NetSwap | | ✅ | zkSync Era | Odos
OpenOcean
SyncSwap
1Inch
MuteSwap | | ✅ | XRP Ledger | - | | ✅ | Cardano | - | | ✅ | Polkadot | - | | ✅ | Litecoin | - | | ✅ | Monero | - | | ✅ | Dash | - | | ✅ | Tezos | - | | ✅ | XDC | - | | ✅ | Filecoin | - | | ✅ | TON | Coffee Swap
DeDust
Tonco | | ✅ | Cosmos | - | | ✅ | Aptos | - | | ✅ | Stellar | Rubic's Stellar API | | ✅ | Neo | - | | ✅ | PulseChain | PulseX V1, V2 | | ✅ | Polygon zkEVM | OpenOcean
QuickSwap V3 | | ✅ | Linea | Odos
OpenOcean
Rango
Squid
SyncSwap
iZUMi | | ✅ | Mantle | Odos
OpenOcean
Squid
FusionX
iZUMi | | ✅ | Base | Odos
OpenOcean
Rango
Squid
Aerodrome
iZUMi
1Inch
BaseSwap | | ✅ | Scroll | SyncSwap
OpenOcean
Rango
iZUMi | | ✅ | Manta Pacific | OpenOcean
Symbiosis
iZUMi | | ✅ | Berachain | Kodiak
OpenOcean | | ✅ | Blast | OpenOcean
Fenix V3
iZUMi | | ✅ | Mode | OpenOcean
Kim
Eddy Finance
iZUMi | | ✅ | XLayer | iZUMi | | ✅ | Taiko | iZUMi | | ✅ | Sui | - | | ✅ | Bahamut | SilkSwap
Kujata | | ✅ | Flare | OpenOcean
BlazeSwap
Spark Dex V3
Enosys V3 | | ✅ | Morph | BulbaSwap | | ✅ | Fraxtal | - | | ✅ | Soneium | Kyo Finance | | ✅ | Monad | OpenOcean
Atlantis
Uniswap V2
OctoSwap
iZUMi
Clober | | ✅ | Unichain | Uniswap V3 | | ✅ | Hemi | OkuSwap
SushiSwap
iZUMi | | ✅ | Plasma | deBridge
OpenOcean
OkuSwap | | ✅ | MegaETH | Warp
deBridge | ## **Supported Bridges & Cross-Chain Providers** Bridging the gap between blockchain networks is at the core of what we do. Rubic facilitates cross-chain operations through 30+ bridges, cross-chain providers and intent protocols, ensuring that assets can flow seamlessly from one blockchain to another. These bridges, cross-chain providers and intent protocols serve as the vital connectors in our ecosystem, enabling interoperability like never before. | Status | Provider | | ------ | ----------------- | | ✅ | Across | | ✅ | Arbitrum Bridge | | ✅ | Avalanche Bridge | | ✅ | Connext | | ✅ | Hop | | ✅ | Optimism Gateaway | | ✅ | Osmosis Bridge | | ✅ | Synapse | | ✅ | Thorchain | | ✅ | Wormhole (Mayan) | | ✅ | Celer | | ✅ | Symbiosis | | ✅ | Li.Fi | | ✅ | deBridge | | ✅ | Bridgers | | ✅ | Stargate | | ✅ | ChangeNOW | | ✅ | Squid | | ✅ | Rango | | ✅ | Owlto | | ✅ | Meson | | ✅ | Eddy Finance | | ✅ | Router Protocol | | ✅ | SimpleSwap | | ✅ | Changelly | | ✅ | Relay | | ✅ | Near Intents | | ✅ | Exolix | | ✅ | USDT0 | | ✅ | Quickex | ## **The Rubic Cross-Chain Tools Integrators** Rubic's cross-chain ecosystem is a thriving hub for more than 130 diverse projects, ranging from wallets and DEXs to infrastructure projects. With the power of our API, these projects can seamlessly expand into the world of cross-chain operations across 70+ chains. [Best Wallet](https://bestwallet.com/en), [D'Cent](https://www.dcentwallet.com/en), [PortalX](https://portalxswap.io/) and many others have already harnessed the capabilities of Rubic's technology. They now provide their users with the convenience of on-chain & cross-chain swaps directly within their interfaces. If you're interested in exploring how Rubic's API can transform your project into an on-chain & cross-chain powerhouse, please reach out to our [Business Development team](https://t.me/RubicPartnership). | Integrator | Links | Dev Tool | | --------------- | ---------------------------------------------------------------- | -------- | | PortalX | [https://portalxswap.io/](https://portalxswap.io/) | SDK | | Best Wallet | [https://bestwallet.com/en](https://bestwallet.com/en) | API | | D'Cent | [https://www.dcentwallet.com/en](https://www.dcentwallet.com/en) | API | | HoldStation | [https://holdstation.com/](https://holdstation.com/) | API | | DODO | [https://dodoex.io/en](https://dodoex.io/en) | API | | NFA Trading Bot | [https://x.com/nfa\_club](https://x.com/nfa_club) | API | | Clear Swap | [https://clearswap.io/](https://clearswap.io/) | API | | Blum | [https://www.blum.io/](https://www.blum.io/) | API | | Exolix | [https://exolix.com/](https://exolix.com/) | API | | Radr | [https://www.radrlabs.io/](https://www.radrlabs.io/) | API | | Swapzone | [https://swapzone.io/](https://swapzone.io/) | API | | BazaarSwap | [https://www.bazaarswap.io/](https://www.bazaarswap.io/) | API | | Sumex | [https://sumex.io/](https://sumex.io/) | API | | CrossCurve | [https://crosscurve.fi/](https://crosscurve.fi/) | API | | Palindrome Pay | [https://www.palindromepay.com](https://www.palindromepay.com) | API | | Quickex | [https://quickex.io](https://quickex.io) | API | | LinkiSwap | [https://www.linkiswap.com](https://www.linkiswap.com) | API | | TonX | [https://tonx.trade/](https://tonx.trade/) | API | | Magno | [www.magno.fi](http://www.magno.fi) | API | # MEV-bot protection Source: https://docs.rubic.finance/rubic/overview/mev-bot-protection With measures in place to prevent front-running, enhance transaction rates, and prioritize user privacy, Rubic continues to contribute to the advancement of a safer and more secure crypto ecosystem. ## **Solution Details** MEV Protect Engine by [bloXroute,](https://bloxroute.com/) the latest addition to Rubic’s arsenal, aims to improve the DeFi ecosystem on Ethereum, BNB Smart Chain and Polygon by introducing the Frontrunning Prevention feature to professional and retail traders in scale and benefit the contributors in the process. *bloXroute connects you directly with validator nodes to securely hand off your transactions to protect you from frontrunning.* Read Full Article: [https://cryptorubic.medium.com/enhancing-crypto-security-rubic-integrates-private-rpc-feature-to-prevent-mev-bot-attacks-9dd5366a3d1a](https://cryptorubic.medium.com/enhancing-crypto-security-rubic-integrates-private-rpc-feature-to-prevent-mev-bot-attacks-9dd5366a3d1a) Important to note, that it works only for swaps **on and from Ethereum, BNB Smart Chain & Polygon**. ### **This is how it works:** 1. Private Transaction Submission: * Users submit private transactions on Rubic. 2. bloXroute Processing in BDN: * bloXroute, within its Blockchain Distribution Network (BDN), processes private transactions. 3. Direct Routing: * Private transactions are routed directly to specific destinations: * Ethereum: Sent to the partner block builder. * BSC: Sent to bloXroute’s block builder. * Polygon: A just-in-time delivery mechanism is used to reduce the chance of frontrunning. 4. Avoiding Public Mempool (For Ethereum and BNB Chain): * Private transactions are not propagated to the public mempool. * This mitigates the risk of frontrunning and sandwich attacks. *In essence, bloXroute processes private transactions, routes them to designated destinations, labels them as private, and ensures they are not exposed to the public mempool, enhancing security against frontrunning and sandwich attacks.* ## **User-Centric Approach** At Rubic, we prioritize simplicity and user-friendliness in every aspect of our platform. To ensure a seamless experience, we have introduced an effortless switch on process for Private RPC. When you engage in a swap exceeding \$1,000, our platform takes a proactive approach to safeguard your funds. A specially designed window will automatically appear, presenting you with the option to activate Private RPC for enhanced fund protection. Activating Private RPC is as easy as flipping a switch. No complex procedures or unnecessary steps — just a straightforward, user-friendly experience. Refer to the screenshot below for a visual guide. **Please note:** If you enable the MEV Bot Protection feature on Rubic, it’s crucial to add new chains with Private RPC and implement transactions through them. Ensure that the new Private RPC Chains are configured as follows: 1. Ethereum: * RPC Endpoint: [https://rubic-eth.rpc.blxrbdn.com](https://rubic-eth.rpc.blxrbdn.com) 2. Binance Smart Chain (BSC): * RPC Endpoint: [https://rubic-bnb.rpc.blxrbdn.com](https://rubic-bnb.rpc.blxrbdn.com) 3. Polygon: * RPC Endpoint: [https://rubic-polygon.rpc.blxrbdn.com](https://rubic-polygon.rpc.blxrbdn.com) ## **User Benefits:** * Enhanced Security Measures: Activate Private RPC to fortify the security of your funds, especially for high-value swaps. * User-Friendly Controls: A simple switch is all it takes to enable this advanced security feature, ensuring a hassle-free experience for every user. * Transparent Security Options: The special window provides clear and transparent options, empowering you to make informed decisions about your fund protection preferences. Rubic is committed to provide the best user experience, and MEV-bot protections is another significant step in building this. We want you to feel confident while swapping by automating the process for big amounts’ swaps and easily activating the feature in our app’s UI. Your security is our priority, and with Private RPC, we ensure that protecting your funds is both intuitive and effective. # Overview Source: https://docs.rubic.finance/rubic/overview/overview Rubic's Best Rate Finder for users and dApps aggregates 340+ DEXs, bridges, intent protocols and privacy solutions across 70+ blockchains. Rubic was born in 2020, at the peak of DeFi Summer, when cross-chain trading was fragmented and every blockchain felt like its own isolated island. For the past five years, we’ve been building a solution to connect those islands into a single, seamless experience. One interface. Unified liquidity. The smoothest possible user journey across chains. Rubic’s Best Rate Finder was among the first to step into this space, aggregating fast, cost-efficient, and secure DEXs, bridges, intent-based protocols, privacy solutions and other aggregators. All within one ecosystem. The mission has always been simple: make cross-chain activity effortless, accessible, and truly unified. Now, you don't need to roam around Web3 and compare DEXs and bridges for rates - Rubic does it in seconds. We enable swaps on and across 70+ chains, supporting 70,000 tokens and over 1,000,000 pairs, all with the best routes across 340+ DEXs, bridges, intent protocols, privacy solutions. Rubic has **already simplified cross-chain trading**. **Now we’re doing the same for privacy.** We prioritise integrating emerging chains **from day one**, often before giant DEXs and on-chain aggregators do, so users can access the latest and most in-demand networks. And on top of that, we **add new tokens from day** **one** and **onboard tokens on demand**. Rubic offers **1:1 stable-to-stable swaps** with no hidden fees, no slippage, just pure value. With whale-friendly and low-barrier swaps, users can start trading from just \$0.50, **no entry barriers**, while also executing **multi-million-dollar transactions** at the best rates. [Understanding Rubic: A Comprehensive Overview By Messari](https://messari.io/report/understanding-rubic) Rubic has been selected for the Top Growth Programs: [Sony Incubation Program](https://astar.network/incubation) (2023), [Consensys Scale Program](https://consensys.io/scale-program) (2024), Solana Superteam (2025). Rubic'secosystem ## **Focusing on Chain Abstraction** | **Chain Abstraction Principles** | **Rubic** | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Asset Management Abstraction** | Rubic’s **Best Rate Finder App** now features **“All Chains”**, a powerful addition that enhances the chain abstraction experience, allowing users to **monitor all their tokens across multiple networks in one place**. Besides, this new category provides a seamless way to explore the **most popular tokens, top gainers & losers across all supported blockchains** in a single view. Furthermore, users can now easily locate a specific token on **every available chain**, simplifying cross-chain asset discovery and trading. | | **Transaction Abstraction** | Thanks to Rubic’s smart routing feature, users can execute cross-chain token swaps in **a single multi-hop transactio**n – eliminating the hassle of manually navigating multiple DEXs and bridges. | | **Token Bridge Abstraction** | As the Best Rate Finder, Rubic aggregates 70+ blockchains and 360+ **DEXs, bridges, & intent-based protocols** enabling seamless cross-chain interactions. By integrating bridging and protocol actions into a single transaction, Rubic simplifies the process with automated relayers that execute user intents effortlessly. **Aggregated bridges, DEXs & intent-based protocols handle all the work for users**, whether it’s a [cross-chain or on-chain trade](https://rubic.exchange/blog/on-chain-vs-off-chain-transactions-in-crypto/). | | **Multi-Chain Abstraction** | On Rubic, users can seamlessly swap assets to, from, and across EVM, non-EVM, and Layer2 chains, all within a single interface. When swapping to non-EVM chains, for example, one doesn’t need to log in to a non-EVM wallet (like for Bitcoin, Ton, etc.) and simply enter the receiver’s wallet address on a non–EVM chain without needing to log in twice. | ## **0% Protocol Fees** Rubic now offers **zero fees** for swaps under \$100! Most on-chain swaps involving stablecoins or native tokens are also completely free. Additionally, bridging **\$USDT** from popular EVM chains to **TRON** and all swaps with **Solana** are now entirely fee-free on Rubic. For larger swaps or other trade types, fees will depend on the specifics of your transaction. Enjoy seamless and cost-effective swapping with Rubic! ## **Prioritizing Security** Rubic is a decentralized cross-chain and on-chain aggregator. KYC is not required for starting an exchange on the platform. Deposit-based providers like ChangeNOW, SimpleSwap, Changelly, Exolix, Quickex are partially centralized. KYC may be required if a transaction conducted via such a provider is marked as suspicious by the provider's automated risk prevention system. In such cases, KYC is carried out on the provider's side. Please find more details [here](https://dev-docs.rubic.exchange/rubic/overview/support-kyc). Rubic’s tech remains sustainable and secure: your funds always stay in your wallet and never on [app.rubic.exchange](http://app.rubic.exchange). Every transaction is conducted via API by sending calls to providers’ smart contracts. You can always count on 24/7 support. [Learn more](https://dev-docs.rubic.exchange/rubic/overview/security). # Roadmap Source: https://docs.rubic.finance/rubic/overview/roadmap Rubicans, our roadmap's evolved! Roadmap Rubic's 2025 roadmap focuses on chain abstraction, more chains and providers, and a smoother user experience. We're planning to introduce social login and gasless transactions, which removes the need for users to hold native tokens for fees. Enhanced swap tools, such as optimised slippage, dollar-based trades and better provider evaluation, aim to improve UX, routing and execution. In 2025, Rubic is expanding its integrations and liquidity network. There will be a strong focus on wallets, DEXs, and aggregators to integrate the Rubic API and SDK. The platform will add support for new chains and liquidity sources. Also, Rubic plans to introduce strategic partnerships with intent providers to launch highly expected chains from Day 1. The second half of 2025 will bring more customization and simpler access. Developers and integrators will gain access to customizable dashboards, and expanded SDK support, and users will get a lite app version. # Rubic's Private Mode Beta Source: https://docs.rubic.finance/rubic/overview/rubics-private-mode-beta Privacy tools are highly fragmented and often difficult to navigate. To address this, Rubic aggregates 6 compliant privacy solutions: Zama, Hinkal Protocol, Railgun, Privacy Cash, Houdini Swap, and ClearSwap. Beta Access Code: **1984** ➡️ [https://app.rubic.exchange/privacy](https://app.rubic.exchange/privacy) Explore [Rubic's Privacy Manifesto](https://x.com/CryptoRubic/status/2036838886425379009). ## Overview Rubic Private Mode is the first privacy aggregator that enables users to access multiple privacy-preserving solutions in one place. Instead of navigating separate platforms, comparing fees, and evaluating execution times manually, users can interact with all supported providers through a unified interface. Currently, Rubic Private Mode integrates: * Railgun * Zama * Houdini Swap * Privacy Cash * Hinkal Protocol * ClearSwap ## Why Privacy Aggregation Matters Privacy solutions in Web3 differ significantly in how they operate: * **Technology**: Some solutions are fully decentralized, while others rely on CEX routing. * **Execution Time**: Transactions may complete in minutes or take up to an hour depending on the provider. * **Fees**: Costs vary based on protocol design and routing mechanisms. * **Supported Assets & Networks**: Each solution supports a different set of tokens and blockchains. Manually comparing these factors across multiple platforms can be complex and inefficient. Rubic Private Mode eliminates this friction by aggregating and standardizing this information. ## How Rubic Private Mode Works The interface is consistent with the standard Rubic experience. Similar to how Rubic aggregates liquidity and finds optimal routes for cross-chain swaps, Private Mode aggregates privacy providers and presents them in a structured format. ## Key Differences Between Privacy Providers Rubic Private Mode emphasizes transparency by displaying the core differences between providers side by side. ### Available Evaluation Criteria **1. Technology**\ Describes the underlying mechanism used to ensure privacy (e.g., encryption models, shielding mechanisms, or routing through intermediaries). **2. Time**\ Indicates the estimated duration required to complete the transaction.\ For example, a higher time indicator may correspond to execution times of up to one hour. **3. Fees**\ Represents the cost of using the selected provider.\ Higher fee indicators correspond to higher transaction costs. **4. Steps to Target Action**\ Specifies how many user interactions are required before completing the transaction.\ Examples include: * Signing a message * Shielding tokens before execution * Completing intermediate steps Some providers allow direct swaps, while others require additional preparation. ## Transparency by Design The goal of Rubic Private Mode is not only convenience but also clarity. By presenting all critical variables, technology, cost, speed, and required steps, in a single interface, users can make informed decisions based on their priorities. Rather than navigating multiple tools and workflows, Rubic enables users to choose the most suitable privacy solution based on what matters most to them: * Faster execution * Lower cost * Higher privacy guarantees ## Rubic's Privacy Roadmap We’ve just taken our first steps into the privacy landscape. Next, we’ll expand our aggregation of privacy solutions and roll out a privacy-focused aggregation API. At the same time, we’ll keep refining the UX—making privacy simple, intuitive, and accessible for anyone. Image # Security Source: https://docs.rubic.finance/rubic/overview/security As one of the seasoned players in the cross-chain market, Rubic has elaborated on the robust practices of maintaining security for its users along with API/SDK integrators. A high level of security is one of Rubic’s top priorities, and this is what makes Rubic stand out from the crowd in terms of security: * The integration of multiple bridges and DEXs allows Rubic to **switch off the provider that gets out of operation**, and redirect the user to a different, working one. * Rubic has a large infrastructure, team, and developer support, which allows for elaborating on more innovative measures to ensure the safety of swaps. Rubic never keeps users' funds on its frontend, every transaction is performed via API by sending calls to other smart contracts. Rubic's staking and treasury smart contracts use Gnosis Safe enabling secure asset management. **[Rubic's Security Audit By MixBytes](https://github.com/mixbytes/audits_public/tree/master/Rubic) -** April, 2023 [Rubic's Security Audit By Stellar](https://drive.google.com/file/d/1opOuoh0ozdfHuofL6TnVEiHeyk16TsQD/view?usp=sharing) - June, 2026 ## Security History In early 2023, Rubic undertook the following security enhancements: * **Full contract rewrite** before redeployment. * **Independent audit by MixBytes**: all findings were reviewed and resolved in full. * **Dev team restructuring** to strengthen internal security practices and reduce organizational risks to platform security. * **Dedicated security engineer hired** to own security operations on an ongoing basis. * **Contract architecture redesign** to make user funds more secure all smart contract management interfaces now operate behind multisig via Gnosis Safe. * **Operational hardening**: two-factor authentication enforced across the team, automated audit logging configured, and real-time alerts deployed for suspicious behavior. Since those steps were implemented, Rubic has maintained a clean record. The MixBytes audit and updated key management practices are the direct results of lessons learned. We document this history because we believe transparency about past incidents, and a verifiable response to them, is more credible than silence. ## **Rubic’s Security Principles** ### **Sustainability** Due to the aggregation of 340+ bridges and DEXs, Rubic guarantees swaps and sufficient liquidity for a swap even if some of the providers stop operating, run out of liquidity, or get hacked. Thanks to Rubic’s model architecture (Cross-Chain, On-Chain, Status Manager, Token Manager, Revert Manager), it continues to execute basic functions even if there’s something wrong with other modules. ### **Decentralization** To find the best swap deal for most of the cross-chain and on-chain providers, Rubic appeals to the provider’s API, and then the data is processed through their services. ### **Open-Source Software** We’re built on open-source software: Our site, validators code, and smart contracts are publicly visible for maximum transparency ([Github](https://github.com/Cryptorubic)). ### **Grants** Rubic has received grants from major blockchain platforms: Berachain, Celer, deBridge, NEAR, Harmony One, Symbiosis, Bitgert, Polygon, and Telos. ### **Team** Our founders and team have large amounts of experience in the crypto space - starting in 2017 - and you can follow them on their socials. Check out LinkedIn or Twitter. #### **Security Measures** * Audit by [MixBytes](https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mfc9p91Kib4qwOqBj11%2Fuploads%2FsuPyInwWpXE7zLDbsE4c%2FRubic%20Security%20Audit%20Report.pdf?alt=media\&token=6a2ab5a9-f36c-45e5-b14f-43ca2bccf10b) * Status Monitoring * Additional security practices: performance monitoring, accident management, and Rubic’s API & SDK Process Management. ## **Rubic’s Security Pillars** ### **Performance Monitoring** To ensure the high performance of Rubic’s cross-chain tools, Rubic’s team utilizes Provider/Blockchain Monitoring Dashboard, scores providers for stuck transactions, daily volume, refunds, and checks out API live status. Rubic utilizes automated tools for monitoring social networks for any potential risks with bridges or chains. If any issues arise, we use direct channels of communication with all bridges and providers to react quickly. ### **Accident Management** If any critical issue arises with one of Rubic’s integrated providers/blockchains, Rubic’s platform as well as Rubic’s API/SDK continue to function by taking the following measures: All of Rubic’s integrators are immediately notified (via Discord, Telegram). 1. A compromised provider/bridge is paused in the smart contract and switched off for all integrators, whereas Rubic continues operating by redirecting transactions to other providers. 2. In case of any issues with Rubic’s API & SDK, Rubic takes the same actions — immediate notification of its integrators and switching off of the compromised provider/bridge. Rubic’s technical support is also ready to assist 24/7. ### **Rubic’s API & SDK Process Management** Continuous integration and collaboration with other projects allow Rubic to build up the most robust principles of **testing**, **staging**, and **production environment**. Seamless, fast, and secure API & SDK management is fulfilled by the following: 1. A code approval process includes the review of several developers and a release approval process includes the review of the Product Manager and QA. 2. The smart contracts are audited. 3. Rubic uses direct communication channels for updates (new version release updates, comments) to reduce the possibility of installing a compromised version. Rubic is not just a platform enabling cross-chain swaps for individuals, but also a cross-chain toolkit for crypto projects, and all of these principles work for Rubic’s API & SDK integrators as well. Read in more detail how Rubic maintains security for its cross-chain swaps: [https://cryptorubic.medium.com/how-rubic-provides-security-for-its-cross-chain-swaps-37d3a408afe7](https://cryptorubic.medium.com/how-rubic-provides-security-for-its-cross-chain-swaps-37d3a408afe7) Check out Rubic’s stats: [https://dune.com/rubic/rubic-general-dashboard](https://dune.com/rubic/rubic-general-dashboard) ### **Token Security Feature** Rubic App token selector has a special sign in front of every token. The sign shows whether the token is reliable, or if it could be a scam (as per the [GoPlus](https://gopluslabs.io/) database). Goplus There are 4 categories of token reliability/ security: 1. The token is in the Go+ Trust List. 2. The token has no elements of concern. 3. The token code contains some low-risk elements of concern. 4. The token code contains some high-risk elements of concern. You can click on a shield icon if you want to know more details about the token’s reliability. You’ll be transferred to the [GoPlus](https://gopluslabs.io/) page devoted to that particular token security status. GoPlus acts as a “security infrastructure” for Web3, providing open, permissionless, user-driven Security Services. Last updated: July, 2026. # Is KYC required? Source: https://docs.rubic.finance/rubic/overview/support-kyc Rubic is a decentralized cross-chain and on-chain aggregator. KYC is not required for starting an exchange on the platform. Rubic aggregates multiple providers to conduct transactions on the Rubic website. There’s a list of providers which are semi-centralized. Such providers align with global compliance standards to prevent money laundering, fraud, and other illicit activities. These measures include the implementation of KYC/AML procedure. ## **KYC/AML PROCEDURE** What are KYC and AML? KYC (Know Your Customer) and AML (Anti-Money Laundering) are key compliance procedures designed to prevent illegal activities like money laundering, fraud, and terrorism financing. Why might providers request KYC? Providers request KYC/AML to verify user identities, ensure transaction legitimacy, and comply with international laws and industry standards. These measures safeguard the platform and the users from fraud and misuse. How the KYC Procedure Works? Advanced technologies and policies are implemented to detect suspicious activities, ensuring a secure environment for legitimate users. Transactions undergo real-time analysis to identify anomalies or patterns that may indicate fraudulent activities. Identity verification is a key step, particularly for transactions flagged by providers' automated risk prevention systems. Each provider may require users to supply basic identification details. For high-risk cases, providers may require additional information or conduct liveness checks to ensure the authenticity of the user’s identity. The required identification details depend on each provider. ## **LIST OF SEMI-CENTRALIZED PROVIDERS** By using these *providers*, you agree to the providers’ AML/KYC Policy, including the potential requirement to undergo the KYC procedure: 1. ChangeNOW 2. SimpleSwap 3. Changelly 4. Exolix 5. Quickex ### **AML/KYC POLICY OF SEMI-CENTRALIZED PROVIDERS** By using semi-centralized providers on the Rubic website, you agree to the policies of these providers. Please note, it is the responsibility of the users to stay informed about any changes in the providers’ KYC policies. It is recommended to check the policy documents periodically to ensure familiarity with the most current measures and requirements. The full texts of the providers’ policies can be found on their respective websites at the following links: 1. ChangeNOW: [https://changenow.io/terms-of-use/changenow-terms](https://changenow.io/terms-of-use/changenow-terms) 2. SimpleSwap: [https://simpleswap.io/aml-kyc](https://simpleswap.io/aml-kyc) 3. Changelly: [https://changelly.com/aml-kyc](https://changelly.com/aml-kyc) 4. Exolix: [https://exolix.com/aml-kyc](https://exolix.com/aml-kyc) 5. Quickex: [https://quickex.io/docs/aml-policy](https://quickex.io/docs/aml-policy) # Stuck Transactions & Refunds Source: https://docs.rubic.finance/rubic/overview/support-stuck-transactions *When conducting cross-chain transactions on the Rubic platform, most are completed within 2–10 minutes (depending on the chosen networks and provider). However, due to the nature of such transactions, they may occasionally get stuck, requiring refunds from the provider.* ## **Causes Of Stuck Cross-Chain Transactions** There are several reasons why cross-chain transactions get stuck: 1. The transaction exceeds the deadline set by the provider (e.g., 90 minutes). 2. An incorrect wallet address is specified by the user for receiving funds in the target network. 3. The sent token or the token to be received is not supported by the provider. 4. Due to gas price changes during the exchange process, the paid amount of gas is not sufficient to cover the gas fee in the target network. 5. Token price changes during the transaction execution, causing the transaction to get stuck due to the set slippage. ## **Refund Options** In these cases, the provider selected in the transaction processes the refund. Depending on the provider, refunds may occur in the following ways: 1. The user receives the originally sent token in the source network. 2. The user receives a pool token (e.g., USDC, USDT, WETH, ETH) in either the source or target network. ## **Refund Process** In most cases, the refund process is automatic. However, for some providers, users may need to manually request the refund. If your transaction is stuck and you haven’t received a refund in either the source or target network, please contact our support team via official Support Communication channels below: ## **Safety Guarantee** Rest assured, when using Rubic, your funds are always safe! # Tokenomics Source: https://docs.rubic.finance/rubic/overview/tokenomics INTRODUCING RUBIC’S NEW TOKENOMICS - THE WAY FORWARD ## **The New RBC token** As web3’s leading Cross-Chain Tech Aggregator, Rubic has been constantly looking for new ways to both improve its offering while enhancing token utility. As a major step towards this goal, Rubic successfully passed a [‘New Tokenomics For Rubic’ proposal](https://snapshot.org/#/rubicexchange.eth/proposal/0xb0175f4a3f0b3713c393e54c5db01198bea34477783e108a36bc7941efada74f) back in 2022. This proposal unlocked additional token supply for the development of Rubic, along with a new tokenomic structure for the platform and its native token – RBC. The current RBC token is created on [Ethereum](https://etherscan.io/token/0x3330bfb7332ca23cd071631837dc289b09c33333) (ERC-20) and is listed on Uniswap V2, Kraken, ProBit, and MEXC. Rubic’s contract address is [https://etherscan.io/token/0x3330bfb7332ca23cd071631837dc289b09c33333](https://etherscan.io/token/0x3330bfb7332ca23cd071631837dc289b09c33333). RBC is at the heart of Rubic’s ecosystem and thanks to the new tokenomics, has the following token utility: * Loyalty program to stimulate platform’s usage * Fee sharing mechanism via Staking * SDK subscriptions & Integration service fees in RBC * Grant programs for API & SDK integrators will be covered in RBC * Governance: Token holders can participate in decentralized decision-making * Distribution of partners’ airdrops to RBC holders ## **RBC Token On Arbitrum** We've added liquidity to the RBC token on Arbitrum, giving you new trading opportunities. Now you can easily buy RBC with lower fees directly on [Rubic.exchange](http://Rubic.exchange) or on [CamelotDEX](https://app.camelot.exchange/?token2=0x10aAeD289a7b1B0155bF4b86c862f297E84465e0), Arbitrum’s native DEX. You can find RBC (ARB) on [CoinMarketCap](https://coinmarketcap.com/currencies/rubic/) (search for "Rubic" or use the contract address: `0x10aAeD289a7b1B0155bF4b86c862f297E84465e0`). If you hold RBC on Ethereum, you can easily bridge it to Arbitrum via the Rubic App at a 1-to-1 rate in just 10 minutes: [https://app.rubic.exchange/?from=RBC\&to=RBC\&fromChain=ETH\&toChain=ARBITRUM\&amount=50000](https://app.rubic.exchange/?from=RBC\&to=RBC\&fromChain=ETH\&toChain=ARBITRUM\&amount=50000). To reverse the process, you can use Arbitrum’s official bridge on Rubic, though it'll take approximately 6-7 days or enjoy hassle-free cross-chain swaps from RBC on Arbitrum at [https://app.rubic.exchange/](https://app.rubic.exchange/). *\*Currently, RBC on Arbitrum is not supported by any CEXs.* ## **TOKEN SUPPLY AND LOCK PERIODS** As of now, the total supply is 187,007,471 RBC. Here you can find the latest mints split and the forecast for 2024: [https://docs.google.com/spreadsheets/d/1n0XTEJcZxPwKT65XhVBEXR6dX7KLT3efJVuf-r9qDAU/edit#gid=0](https://docs.google.com/spreadsheets/d/1n0XTEJcZxPwKT65XhVBEXR6dX7KLT3efJVuf-r9qDAU/edit#gid=0). This document is regularly updated and publicly available. The max supply that can be minted as per the new contract by 2028 is 1,000,000,000 RBC. However, this amount might never be minted, as the emission is driven purely by the project’s business needs. You can check out the draft emission dates for 2024 [here](https://docs.google.com/spreadsheets/d/1n0XTEJcZxPwKT65XhVBEXR6dX7KLT3efJVuf-r9qDAU/edit#gid=1860141076). ## **Explanatory notes:** Pre-seed holders - i.e. holders of the previous version of the RBC token. Marketing: We expanded our user base 3 times in 2023, and for 2024 we also have aggressive growth plans – including massive user acquisition campaigns and major product updates. To successfully execute, these plans will require extensive promotion and hence a designated marketing budget.. We’re also planning to launch grants for integrators. The “Ecosystem growth” emission is currently locked and, therefore, can only be financed from Marketing. Loyalty: The Swap to Earn program will be updated in 2024 and will include several new incentive mechanisms that reward referrals, staking and recurring usage of the platform. Seed: potential investors. Seed emission is hard to predict timing-wise and therefore is not included in this forecast, but may happen. Ecosystem growth: grants for Rubic’s integrators and promotion of our B2B tools. Locked till 12.12.2024. Listing: the number for listing is a very rough forecast, as it involves negotiations, and therefore may also change. Tokenlockperiods ## **Explanatory notes:** The date from which lock periods are calculated is 12.12.2022, the date of the token launch. The locking and vesting periods will help prevent token price fluctuation (see the slide below for details). Please note, that the slide above reflects the potential amount of tokens and their vesting periods. These tokens may never need to be minted if there’s no substantial business need (like new listing, liquidity, ecosystem development, etc.). You may see that some tokens are already unlocked but still not minted - this means there was no business need for minting them. For more insights on potential mints, refer to the forecast [here](https://docs.google.com/spreadsheets/d/1n0XTEJcZxPwKT65XhVBEXR6dX7KLT3efJVuf-r9qDAU/edit#gid=1860141076). ## **Retrodrop to Holders** Following the structure of Rubic’s new tokenomics, the Rubic team launched the much-anticipated RBC Retrodrop, a token distribution event that rewards our holders for their unwavering loyalty. Discover details:[ https://cryptorubic.medium.com/rbc-retrodrop-for-og-holders-10b8b33d403f](https://cryptorubic.medium.com/rbc-retrodrop-for-og-holders-10b8b33d403f) If you have any questions, please contact us at [support@rubic.finance](mailto:support@rubic.finance). ### ****Rubic Community Treasury address (Arbitrum):**** `0xc9F5DD51d7BAae25119F37bE2164062b6146Af32` ### **Rubic's Treasury Multisig Wallet (Scroll):** `0x757782807AF40Cf4ce4652658Db4185084C5994F` ### **Token address on Ethereum:** `0x3330BFb7332cA23cd071631837dC289B09C33333` ### **Team wallets:** `0x483557C3B44362eBDA69B9A1e9bb2C27073AE1Bd` `0xba4Ad0caCee563FbABafBBeDf1cDBd39dBeebFAC` ### **Liquidity address on Ethereum:** `0xEF19e87FA5F47B81B2C4AD25EDE64dbaD1cd3BD9` ### **Token address on Arbitrum:** `0x10aaed289a7b1b0155bf4b86c862f297e84465e0` ### **Liquidity address on Arbitrum:** `0x483557C3B44362eBDA69B9A1e9bb2C27073AE1Bd` # Statuses Source: https://docs.rubic.finance/statuses # Tracking Status After a swap transaction is broadcast, you need to track its completion on the destination chain. Rubic SDK provides both a direct status method and a higher-level polling helper. *** ## getStatusExtended Fetches the current status of a cross-chain transaction in a single request. ```typescript theme={null} const status = await sdk.getStatusExtended(params: ExtendedStatusRequestInterface): Promise ``` ### Request parameters | Field | Type | Required | Description | | ----------- | -------- | ------------- | ---------------------------------------------- | | `id` | `string` | ✅ | Trade ID from the `swap` / `swapBest` response | | `srcTxHash` | `string` | *(see below)* | Source chain transaction hash | > **When is `srcTxHash` required?** > > * **Decentralized providers** (bridges, on-chain DEXes): both `id` and `srcTxHash` are required > * **Deposit-based providers** (ChangeNOW, Exolix, etc.): only `id` is needed ### Example ```typescript theme={null} const status = await sdk.getStatusExtended({ id: 'trade-uuid-from-swap-response', srcTxHash: '0xabc123...', }); console.log(status.status); // → 'PENDING' console.log(status.destinationTxHash); // → null (still pending) or '0x...' console.log(status.destinationNetworkTitle); // → 'BSC' console.log(status.destinationNetworkChainId); // → 56 ``` ### Response: StatusResponseInterface | Field | Type | Description | | --------------------------- | ------------------- | -------------------------------------------------- | | `status` | `TransactionStatus` | Current status (see table below) | | `destinationTxHash` | `string \| null` | Destination chain tx hash (available on `SUCCESS`) | | `destinationNetworkTitle` | `string \| null` | Human-readable destination chain name | | `destinationNetworkChainId` | `number \| null` | Destination chain ID | *** ## Transaction statuses | Status | Terminal | Description | | ------------------------------ | -------- | --------------------------------------------------------- | | `PENDING` | | Transaction received, waiting for confirmation | | `LONG_PENDING` | | Taking longer than expected, still processing | | `WAITING_FOR_TRUSTLINE` | | Waiting for XRP/Stellar trustline to be established | | `WAITING_FOR_REFUND_TRUSTLINE` | | Waiting for trustline before a refund can be issued | | `SUCCESS` | ✅ | Swap completed successfully | | `READY_TO_CLAIM` | ✅ | Funds ready to claim on destination (manual claim needed) | | `FAIL` | ✅ | Transaction failed | | `REVERT` | ✅ | Transaction was reverted | | `REVERTED` | ✅ | Transaction was reverted (provider-specific variant) | | `NOT_FOUND` | ✅ | Transaction not found (invalid ID or too early) | | `INDETERMINATE` | ✅ | Status cannot be determined | Terminal statuses mean no further polling is needed. *** ## waitForStatus A built-in polling helper that calls `getStatusExtended` on an interval until a terminal status is reached. ```typescript theme={null} sdk.waitForStatus( params: ExtendedStatusRequestInterface, options?: WaitForStatusOptions ): Promise ``` ### Options | Field | Type | Default | Description | | ---------------- | ------------------ | --------- | -------------------------------------------------------------------- | | `interval` | `number` | `3000` | Polling interval in ms | | `timeout` | `number` | `300_000` | Max wait time in ms before rejecting with `Error('Polling timeout')` | | `onStatusUpdate` | `(status) => void` | — | Callback fired on every poll, including intermediate statuses | ### Example — basic usage ```typescript theme={null} const finalStatus = await sdk.waitForStatus({ id: swapData.id, srcTxHash: tx.hash, }); if (finalStatus.status === 'SUCCESS') { console.log('Destination tx:', finalStatus.destinationTxHash); } ``` ### Example — with all options ```typescript theme={null} const finalStatus = await sdk.waitForStatus( { id: swapData.id, srcTxHash: tx.hash }, { interval: 5_000, // poll every 5 seconds timeout: 600_000, // give up after 10 minutes onStatusUpdate: (status) => { console.log('[%s] Status: %s', new Date().toISOString(), status.status); updateUI(status); }, } ); ``` ### Example — handling all outcomes ```typescript theme={null} try { const finalStatus = await sdk.waitForStatus( { id: swapData.id, srcTxHash: tx.hash }, { interval: 5000, timeout: 300_000 } ); switch (finalStatus.status) { case 'SUCCESS': showSuccess(finalStatus.destinationTxHash!); break; case 'READY_TO_CLAIM': // User needs to manually claim tokens on the destination chain showClaimButton(finalStatus); break; case 'FAIL': case 'REVERT': case 'REVERTED': showError('Swap failed. Please try again.'); break; case 'NOT_FOUND': case 'INDETERMINATE': showError('Status unknown. Check the explorer.'); break; } } catch (err) { if (err instanceof Error && err.message === 'Polling timeout') { showError('Swap is taking too long. Check the explorer manually.'); } else { throw err; } } ``` ### Example — deposit-based providers (no srcTxHash) ```typescript theme={null} const depositData = await sdk.swapDepositTrade({ /* params */ }); // No tx hash — the user sent funds manually to the deposit address const finalStatus = await sdk.waitForStatus( { id: depositData.id }, // srcTxHash is not needed { interval: 10_000, timeout: 1_800_000 } ); ``` *** ## READY\_TO\_CLAIM — Arbitrum Bridge When `status === 'READY_TO_CLAIM'`, the swap used the Arbitrum Bridge and requires a manual on-chain claim on the destination chain. Use [`claim()`](../utility#claim) to build the claim transaction: ```typescript theme={null} if (finalStatus.status === 'READY_TO_CLAIM') { const claimTx = await sdk.claim({ sourceTransactionHash: tx.hash, fromBlockchain: 'ETHEREUM', }); await signer.sendTransaction(claimTx); } ``` # Swap Source: https://docs.rubic.finance/swap # Executing Swaps Swap methods return transaction data that you send via your wallet or web3 library. **No transaction is broadcast by the SDK** — it only builds the calldata. *** ## swap Builds transaction data for a route that was previously calculated with `quoteBest` or selected from `quoteAll`. ```typescript theme={null} const swapData = await sdk.swap(params: SwapRequestInterface): Promise ``` ### Request parameters Extends all [quote parameters](./quote#common-request-parameters), plus: | Field | Type | Required | Description | | --------------- | --------- | -------- | --------------------------------------------------------- | | `id` | `string` | ✅ | Trade ID from the quote response | | `fromAddress` | `string` | ✅ | Wallet that will sign and send the transaction | | `receiver` | `string` | ✅ | Recipient address on the destination chain | | `enableChecks` | `boolean` | | Validate balance and gas before building. Default: `true` | | `signature` | `string` | | Wallet auth signature (required for Retrobridge) | | `publicKey` | `string` | | Bitcoin wallet public key (Bitcoin trades only) | | `refundAddress` | `string` | | Refund address for failed deposit trades | ### Example ```typescript theme={null} // Step 1 — quote const quote = await sdk.quoteBest({ srcTokenBlockchain: 'ETH', srcTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC srcTokenAmount: '500', dstTokenBlockchain: 'ARBITRUM', dstTokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831', // USDC on Arbitrum fromAddress: '0xYourWallet', receiver: '0xYourWallet', }); // Step 2 — build tx const swapData = await sdk.swap({ srcTokenBlockchain: 'ETH', srcTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', srcTokenAmount: '500', dstTokenBlockchain: 'ARBITRUM', dstTokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831', fromAddress: '0xYourWallet', receiver: '0xYourWallet', id: quote.id, }); // Step 3 — send (example with ethers.js) const tx = await signer.sendTransaction({ to: swapData.transaction.to, data: swapData.transaction.data, value: swapData.transaction.value ?? '0x0', }); console.log('Sent:', tx.hash); ``` ### Response: SwapResponseInterface | Field | Type | Description | | ----------------------------- | -------------------- | -------------------------------------------- | | `id` | `string` | Trade ID — use this for status tracking | | `transaction.to` | `string` | Contract address to call | | `transaction.data` | `string` | Encoded calldata | | `transaction.value` | `string` | Native token value to send (hex) | | `transaction.approvalAddress` | `string` | Token approval target (if approval needed) | | `estimate` | `EstimatesInterface` | Same as in quote response | | `fees` | `FeesInterface` | Fee breakdown | | `routing` | `RoutingInterface[]` | Step-by-step route | | `warnings` | `ErrorInterface[]` | Non-fatal warnings | | `uniqueInfo` | `object` | Provider-specific IDs (for support/tracking) | *** ## swapBest Combines `quoteBest` + `swap` into a single API call. Use when you don't need to show the user a quote preview. ```typescript theme={null} const swapData = await sdk.swapBest(params: SwapBestRequestInterface): Promise ``` > Same parameters as `swap`, but **without `id`** — the API finds the best route internally. ### Example ```typescript theme={null} const swapData = await sdk.swapBest({ srcTokenBlockchain: 'ETH', srcTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', srcTokenAmount: '0.5', dstTokenBlockchain: 'BSC', dstTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', fromAddress: '0xYourWallet', receiver: '0xYourWallet', }); const tx = await signer.sendTransaction({ to: swapData.transaction.to, data: swapData.transaction.data, value: swapData.transaction.value, }); ``` *** ## swapDepositTrade Returns a **deposit address** instead of calldata. The user manually sends funds to that address — no wallet signing of a smart contract call required. Used with deposit-based providers (ChangeNOW, Exolix, SimpleSwap, etc.). ```typescript theme={null} const data = await sdk.swapDepositTrade(params: SwapDepositRequestInterface): Promise ``` > `fromAddress` is optional. `receiver` is required — it's the destination address where tokens will arrive. ### Example ```typescript theme={null} // First quote deposit routes const quoteResult = await sdk.quoteDepositTrades({ srcTokenBlockchain: 'BTC', srcTokenAddress: '0x0000000000000000000000000000000000000000', srcTokenAmount: '0.05', dstTokenBlockchain: 'ETH', dstTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', receiver: '0xYourEthWallet', }); const bestDepositRoute = quoteResult.routes[0]; // Then get the deposit address const depositData = await sdk.swapDepositTrade({ srcTokenBlockchain: 'BTC', srcTokenAddress: '0x0000000000000000000000000000000000000000', srcTokenAmount: '0.05', dstTokenBlockchain: 'ETH', dstTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', receiver: '0xYourEthWallet', id: bestDepositRoute.id, }); // Show the user where to send funds console.log('Send BTC to:', depositData.transaction.depositAddress); console.log('Amount to send:', depositData.transaction.amountToSend); console.log('Exchange ID:', depositData.transaction.exchangeId); // Extra fields may contain memo, tag, or other provider-specific data if (depositData.transaction.extraFields) { console.log('Extra:', depositData.transaction.extraFields); } ``` *** ## Token approvals ERC-20 swaps may require a token approval before the swap transaction. Use [`checkApprove`](../utility#checkapprove) to determine whether approval is needed, then send the approval transaction first. ```typescript theme={null} const approveInfo = await sdk.checkApprove({ blockchain: 'ETH', tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC walletAddress: '0xYourWallet', spenderAddress: swapData.transaction.approvalAddress!, amount: '500', }); if (approveInfo.needApprove) { // Send the approval tx first await signer.sendTransaction(approveInfo.transaction!); // Then send the swap tx } ``` *** ## Full example with approval check ```typescript theme={null} import { SDK, RubicApiError } from '@cryptorubic/sdk-lite'; const sdk = await SDK.create({ referrer: 'my-app', apiKey: 'KEY' }); try { const quote = await sdk.quoteBest({ srcTokenBlockchain: 'ETH', srcTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', srcTokenAmount: '100', dstTokenBlockchain: 'POLYGON', dstTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174', fromAddress: wallet.address, receiver: wallet.address, }); const swapData = await sdk.swap({ srcTokenBlockchain: 'ETH', srcTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', srcTokenAmount: '100', dstTokenBlockchain: 'POLYGON', dstTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174', fromAddress: wallet.address, receiver: wallet.address, id: quote.id, }); // Approval check if (swapData.transaction.approvalAddress) { const approveInfo = await sdk.checkApprove({ blockchain: 'ETH', tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', walletAddress: wallet.address, spenderAddress: swapData.transaction.approvalAddress, amount: '100', }); if (approveInfo.needApprove) { const approveTx = await signer.sendTransaction(approveInfo.transaction!); await approveTx.wait(); } } // Send swap const tx = await signer.sendTransaction({ to: swapData.transaction.to, data: swapData.transaction.data, value: swapData.transaction.value, }); // Track completion const status = await sdk.waitForStatus( { id: swapData.id, srcTxHash: tx.hash }, { onStatusUpdate: s => console.log(s.status) } ); console.log('Final status:', status.status); } catch (err) { if (err instanceof RubicApiError) { console.error(`API error [${err.code}]: ${err.reason}`); } } ``` # Utility Source: https://docs.rubic.finance/utility # Utility Methods Utility methods handle approvals, allowances, refunds, and wallet authentication. *** ## allowance Returns the current ERC-20 token allowance granted by a wallet to a spender contract. ```typescript theme={null} const result = await sdk.allowance(params: AllowanceRequestInterface): Promise ``` ### Parameters | Field | Type | Description | | ---------------- | ---------------- | -------------------------------------------- | | `blockchain` | `BlockchainName` | Blockchain where the token lives | | `tokenAddress` | `string` | ERC-20 token contract address | | `walletAddress` | `string` | Token owner address | | `spenderAddress` | `string` | Spender contract address (e.g. Rubic router) | ### Example ```typescript theme={null} const result = await sdk.allowance({ blockchain: 'ETH', tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC walletAddress: '0xYourWallet', spenderAddress: '0xRubicRouterAddress', }); console.log('Allowance (wei):', result.allowance); // → '1000000000' (1000 USDC) ``` *** ## checkApprove Determines whether an ERC-20 approval is needed and, if so, returns the approval transaction data ready to send. ```typescript theme={null} const result = await sdk.checkApprove(params: ApproveRequestInterface): Promise ``` ### Parameters Extends `AllowanceRequestInterface`, plus: | Field | Type | Description | | ---------------- | ---------------- | ---------------------------------------------------- | | `blockchain` | `BlockchainName` | Blockchain where the token lives | | `tokenAddress` | `string` | ERC-20 token address | | `walletAddress` | `string` | Wallet that will approve | | `spenderAddress` | `string` | Spender to approve | | `amount` | `string` | Token amount to approve in **token units** (not wei) | ### Response: ApproveResponseInterface | Field | Type | Description | | ------------- | ----------------------------------- | ---------------------------------------------------------- | | `needApprove` | `boolean` | Whether an approval transaction is needed | | `transaction` | `TransactionInterface \| undefined` | Approval tx data (present only if `needApprove` is `true`) | | `message` | `string` | Human-readable explanation | ### Example ```typescript theme={null} const approveInfo = await sdk.checkApprove({ blockchain: 'ETH', tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC walletAddress: '0xYourWallet', spenderAddress: swapData.transaction.approvalAddress!, amount: '500', // 500 USDC }); if (approveInfo.needApprove) { console.log('Approval needed:', approveInfo.message); // Send the approval transaction const approveTx = await signer.sendTransaction({ to: approveInfo.transaction!.to, data: approveInfo.transaction!.data, }); await approveTx.wait(); console.log('Approved. Now proceed with the swap.'); } else { console.log('No approval needed:', approveInfo.message); } ``` > **Tip:** The `approvalAddress` field in the `swap` response contains the address to approve tokens for. Always use that value, as it may differ per provider. *** ## claim Returns transaction data for claiming tokens that are ready to be redeemed via the **Arbitrum Bridge** (ETH ↔ Arbitrum). Used when `waitForStatus` resolves with `status === 'READY_TO_CLAIM'`. ```typescript theme={null} const tx = await sdk.claim(params: ClaimRequestInterface): Promise ``` ### Parameters | Field | Type | Description | | ----------------------- | ------------------- | ----------------------------------------------- | | `sourceTransactionHash` | `string` | The source chain transaction hash | | `fromBlockchain` | `EvmBlockchainName` | Source blockchain: `'ETHEREUM'` or `'ARBITRUM'` | ### Example ```typescript theme={null} const status = await sdk.waitForStatus({ id: swapData.id, srcTxHash: tx.hash }); if (status.status === 'READY_TO_CLAIM') { const claimTx = await sdk.claim({ sourceTransactionHash: tx.hash, fromBlockchain: 'ETHEREUM', }); const claimResult = await signer.sendTransaction(claimTx); console.log('Claimed:', claimResult.hash); } ``` *** ## celerRefund Returns transaction data for refunding a **failed Celer Bridge** cross-chain swap. ```typescript theme={null} const tx = await sdk.celerRefund(params: CelerRefundRequestInterface): Promise ``` ### Parameters | Field | Type | Description | | ----------------------- | ---------------------------- | --------------------------------- | | `sourceTransactionHash` | `string` | The source chain transaction hash | | `fromBlockchain` | `CbridgeSupportedBlockchain` | Source blockchain | ### Example ```typescript theme={null} const refundTx = await sdk.celerRefund({ sourceTransactionHash: '0xFailedTxHash', fromBlockchain: 'ETH', }); await signer.sendTransaction(refundTx); ``` *** ## authWalletMessage Returns a message that the user must sign with their wallet for **Retrobridge** provider authentication. The resulting signature must be passed in the `signature` field of the `swap` request. ```typescript theme={null} const result = await sdk.authWalletMessage(walletAddress: string): Promise ``` ### Example ```typescript theme={null} const { messageToAuth } = await sdk.authWalletMessage('0xYourWallet'); // Sign the message with the user's wallet const signature = await signer.signMessage(messageToAuth); // Use the signature in the swap request const swapData = await sdk.swap({ // ... other params ... signature, }); ``` *** ## healthcheck Verifies the API is online. ```typescript theme={null} const result = await sdk.healthcheck(): Promise // → 'I am alive' ``` Useful for readiness checks before showing the UI: ```typescript theme={null} try { await sdk.healthcheck(); // setApiAvailable(true); } catch { // setApiAvailable(false); // showMaintenanceBanner(); } ```