Smart Deposit Addresses Integration | Docs

Default limits apply to Smart Deposit Addresses for initial testing purposes:

500 total SDAs
50 SDAs generated per hour

Please contact us to lift your limits.

Introduction

Smart Deposit Addresses are the core deposit primitive in the Rhino.fi Stablecoin Activation Stack. Generate one address per user; Rhino.fi handles chain detection, routing, settlement, and compliance automatically. This allows customers to easily send any supported asset to the Smart Deposit Address, without worrying about needing a specific chain-token pairing, but allows clients to receive the funds in their required chain-token pairing, and take additional activation steps to ensure that funds land in a usable balance.

How it works

Authentication

Get a JWT to authenticate your requests.

Fetching Smart Deposit Address configs

Retrieve supported chains and tokens.

Generate address

Call our API to generate a Smart Deposit Address which will allow funds to be received across multiple chains. We strongly recommend generating an SDA on all available EVM chains to ensure that funds accidentally sent by customers to the wrong chain and automatically detected. More best practices can be found here.

Transfer funds

Any supported assets can then be sent to the Smart Deposit Address.

Receive funds

Rhino.fi monitors the Smart Deposit Addresses to detect when funds are received and will then take the necessary bridging and swapping actions to ensure funds land in an activated state on the specified destination.

Smart Deposit Addresses are reusable and can be used for multiple bridges indefinitely (see caveats below).

Fees

Your Rhino.fi PAYG/Subscription covers use of both the Rhino.fi Bridge as well as Smart Deposit Addresses. Therefore your Flow Credit allocation is across both. To understand how many Flow Credits a transaction into a Smart Deposit Address will consume, the POST/bridge/quote/bridge-swap/user endpoint should be called with the isSda parameter set as true. The response will also provide a fee breakdown showing what additional fees are charged to the client (such as onchain gas fee charges) or are being passed onto the end customer. Where a Client Surcharge is being applied, this will be shown in the fee amount and settled up to the client within end of month invoicing. Learn more about Rhino.fi’s fee structure here. N.B for clients on the legacy pricing structure, any fees will be deducted from the amount settled on the destination chain.

Advanced Fee and Limit ManagementRhino.fi has the Advanced Fee and Limit Management extension which is optimal for any clients who are looking to set up more complex or variable fee structures - beyond passing on a simple Client Surcharge to their end customers. See Advanced Fee & Limit Management for details and please reach out to your Rhino.fi Account Manager or the partnership team to discuss your optimal fee set up: partnerships@rhino.fi.

Smart Deposit Address Expiration

Smart Deposit Addresses are re-usable, meaning they can function as a receive for customer funds repeatedly and Rhino.fi will continue to actively monitor for deposits and process bridging and swapping activity to the destination of choice. Rhino.fi will monitor a Smart Deposit Address for 7 years, and thereafter it switches into an unmonitored state to conserve resources.

Supported chains and tokens

Smart Deposit Addresses are enabled across a wide variety of tokens and chains. This is a growing list and based on client demand so please do reach out with any specific token or chain requests. The general bridge config endpoint provides a boolean enabledDepositAddress flag that can be used to find chains that Smart Deposit Addresses are enabled for. Example:

const response = await fetch('https://api.rhino.fi/bridge/configs')

The response will then specify which chains have Smart Deposit Addresses enabled:

{
  "ETHEREUM": {
    "name": "Ethereum",
    ...,
    "enabledDepositAddress": true,
  },
  "TON": {
    "name": "Ton",
    ...,
    "enabledDepositAddress": false,
  },
}

To get the list of tokens supported between a deposit chain and destination chain you can execute the following code:

const depositChain = 'ETHEREUM'
const destinationChain = 'BASE'
const tokenOut = 'USDT' // optional
const response = await fetch(`https://api.rhino.fi/sda/deposit-addresses/${depositChain}/${destinationChain}/supported-tokens?tokenOut=${tokenOut}`, {
  method: 'GET',
  headers: {
    'authorization': 'YOUR_JWT',
  },
})

It will return the list of supported tokens between the 2 specified chains along with their associated deposit limit. For the exact response format and more details, see the API Reference.

API interactions

The following examples showcase the use of our API to manage Smart Deposit Addresses. All those calls require authentication, see details on this here.

Generating a Smart Deposit Address

You can generate a new Smart Deposit Address with the following API call:

const response = await fetch('https://api.rhino.fi/sda/deposit-addresses', {
  method: 'POST',
  body: JSON.stringify({
    depositChains: ['ETHEREUM'],
    destinationChain: 'BASE',
    destinationAddress: '0x123...',
  }),
  headers: {
    'Content-Type': 'application/json',
    'authorization': 'YOUR_JWT',
  },
})

The response will then look like this:

[{
  "depositChain": "ETHEREUM",
  "depositAddress": "0x456...",
  "destinationChain": "BASE",
  "destinationAddress": "0x123...",
  "supportedTokens": [
    {
      "symbol": "USDT",
      "address": "0x789...",
      "maxDepositLimitUsd": 100000,
      "minDepositLimitUsd": 10,
    }
  ],
  "isActive": true,
}]

For the exact response format and more details, see the API Reference. The first highlighted line contains the generated Smart Deposit Address. Funds can be sent there to be bridged.
However, only tokens from the supportedTokens list will be processed. Transfers of tokens that are not in this list will not be processed. Transfers that are smaller than the minDepositLimitUsd or larger than the maxDepositLimitUsd will not be processed (there is a “grace” window to account for different price sources and price fluctuations). If this happens, funds can be returned through our Account Management team.

Multiple deposit chains

You can provide multiple deposit chains in the request. The API will then generate one Smart Deposit Address that can be used on all the provided chains. This is why the response is also a list - one element for each chain provided. The Smart Deposit Addresses in the individual elements will be identical in this case.
Please note that providing multiple deposit chains only works for EVM chains currently. Only then can the same address be used for all of them.

Swaps

When creating a Smart Deposit Address you can also specify a tokenOut field. This will cause all withdrawals on the destination chain to be in that token, swapping if needed. This is currently only supported for stablecoins (USDC and USDT). The given tokenOut needs to be a bridgable token on the destination chain, otherwise creation of the SDA will fail.

1:1 Stablecoin Swaps (Extension)If your account has the 1:1 Stablecoin Swaps extension enabled, cross-stable conversions (e.g. USDT deposited → USDC settled) are processed at a guaranteed 1:1 rate. No slippage and no exposure to market price. This applies automatically to any SDA configured with a cross-stable tokenOut. Contact your account representative to enable this extension.

Post Bridge Data

Rhino.fi provides the option to execute contract calls as part of the withdrawal process on the destination chain so that funds can land in a fully activated state. For security reasons, only predefined actions are available. Please contact us with details on your use case if interested.

Refund address

Rhino.fi provides the option to pass a refund address when creating a Smart Deposit Address so that, in the case of an unsuccessful transaction, funds can be reverted back to the provided address. However we recommend that any refunds are dealt with on a case by case basis directly with our Account Management team instead, to ensure that customer funds sent from pooled locations; such as a CEX, are able to be handled successfully. We therefore suggest that this field is not used unless you are highly confident that the customer will be able to access the sending address again.

Custom data and reusing of addresses

When creating a Smart Deposit Address you can provide a addressNote field to be stored in our database. This field will be returned from all status endpoints as well.
Additionally, a reusePolicy can be specified when creating a Smart Deposit Address. It can have the following values:

reuse-existing: Reuse an existing Smart Deposit Address if it exists. Only create a new one if no existing address matches the given parameters.
create-new: Always create a new Smart Deposit Address.

When no reusePolicy is specified it defaults to reuse-existing. To determine if a Smart Deposit Address already exists, the following combination of fields is used:

depositChain
destinationChain
destinationAddress
userId (only Smart Deposit Addresses previously created by you will be considered)
addressNote if provided
tokenOut if provided
postBridgeData if provided
webhookUrl if provided
refundAddress if provided

Example use cases for this feature:

Your users have unique destination addresses and you want to show users their previously used Smart Deposit Address.
You consolidate multiple Smart Deposit Addresses into the same destination address but store a user ID in the addressNote field to make sure to only have one address per user.

Checking Smart Deposit Address status

You can also check the current status of a Smart Deposit Address with the following call:

const depositAddress = '0x123...'
const depositChain = 'ETHEREUM'
const response = await fetch(`https://api.rhino.fi/sda/deposit-addresses/${depositAddress}/${depositChain}`, {
  headers: {
    'authorization': 'YOUR_JWT',
  },
})

The response format will be the same as the one returned when generating a new Smart Deposit Address with the exception of the destinationAddress. That field will only be included if the request was made with a secret API key. For the exact response format and more details, see the API Reference.

Checking Smart Deposit Address history

You can check the history of a Smart Deposit Address with the following call:

const depositAddress = '0x123...'
const depositChain = 'ETHEREUM'
const response = await fetch(`https://api.rhino.fi/sda/deposit-addresses/${depositAddress}/${depositChain}/history`, {
  headers: {
    'authorization': 'YOUR_JWT',
  },
})

The response will contain a list of transfers that have been processed through the Smart Deposit Address. By default it gives you the transfers from the last 7 days. To see older transfers you can provide a from and to query parameter with a timestamp in milliseconds. Only a SECRET_ key is allowed to access history. For the exact response format and more details, see the API Reference.

Checking Smart Deposit Address bridge status with a PUBLIC API key

Generally the above history endpoint can be used to track the bridges through a Smart Deposit Address. However it is not possible to use this in a frontend integration as a SECRET API key would be exposed in an unsafe browser environment.
To also track bridges in this case, a public status endpoint exists. However, this endpoint additionally takes a destinationAddress as query parameter that has to match the requested Smart Deposit Address (this value should still be available in the local state after creating a Smart Deposit Address). If it does not match, the request will be rejected.
Example:

const depositAddress = '0x123...'
const depositChain = 'ETHEREUM'
const destinationAddress = '0x456...'
const response = await fetch(`https://api.rhino.fi/sda/deposit-addresses/${depositAddress}/${depositChain}/public-status?destinationAddress=${destinationAddress}`, {
  headers: {
    'authorization': 'YOUR_JWT_FROM_SECRET_KEY',
  },
})

The response will contain the last bridge (accepted or rejected) through the Smart Deposit Address in the lastBridges field. If this array is empty it means that no transfer has been picked up yet.
Please note that this array will currently only contain the last event. In the future this endpoint will be expanded with the option to return all bridges after a certain timestamp.

Search your addresses

Rhino.fi provides an endpoint that allows you to search for your Smart Deposit Addresses with some optional filters. This endpoint is authenticated and will only return the addresses associated with your user. The result is paginated and you can set the pageToken field to get to the next page. If not provided, it will return the first page of results and a nextTokenPage value that can be used to query for the next page. The following filters are available (all are optional and can be combined):

addressNote
depositChain
destinationChain
destinationAddress: requires destinationChain to be set as well

// all filters are optional and can be combined
const addressNote = 'my_note'
const depositChain = 'ETHEREUM'
const destinationChain = 'BASE'
const destinationAddress = '0x....'

const pageSize = 20 // optional, default to 20, max 50
const pageToken = "eyJkZXBvc2l0Q2hhaW4iOiJCQVNFIiwiZGVwb3NpdEFkZHJlc3MiOiIweDlmYTE1MDdiNTY0YzRlNWM1YmJjN2E5Yzc1ZWQ1MmFhMTc5ODIxNjkifQ==" // optional, returns the first page of results if not provided

const response = await fetch(
  `https://api.rhino.fi/sda/deposit-addresses/search?addressNote=${addressNote}&depositChain=${depositChain}&destinationChain=${destinationChain}&destinationAddress=${destinationAddress}&page=${page}&limit=${limit}`,
  {
    method: 'GET',
    headers: {
      'authorization': 'YOUR_JWT',
    },
  },
)

For the exact response format and more details, see the API Reference.

Get Started

SDK

Migration guides

Webhook

API Integration

Smart Contracts

Widgets

General information

Smart Deposit Addresses

Introduction

How it works

Fees

Smart Deposit Address Expiration

Supported chains and tokens

API interactions

Generating a Smart Deposit Address

Multiple deposit chains

Swaps

Post Bridge Data

Refund address

Custom data and reusing of addresses

Checking Smart Deposit Address status

Checking Smart Deposit Address history

Checking Smart Deposit Address bridge status with a PUBLIC API key

Search your addresses

​Introduction

​How it works

​Fees

​Smart Deposit Address Expiration

​Supported chains and tokens

​API interactions

​Generating a Smart Deposit Address

​Multiple deposit chains

​Swaps

​Post Bridge Data

​Refund address

​Custom data and reusing of addresses

​Checking Smart Deposit Address status

​Checking Smart Deposit Address history

​Checking Smart Deposit Address bridge status with a PUBLIC API key

​Search your addresses

Introduction

How it works

Fees

Smart Deposit Address Expiration

Supported chains and tokens

API interactions

Generating a Smart Deposit Address

Multiple deposit chains

Swaps

Post Bridge Data

Refund address

Custom data and reusing of addresses

Checking Smart Deposit Address status

Checking Smart Deposit Address history

Checking Smart Deposit Address bridge status with a PUBLIC API key

Search your addresses