Table of Contents

Custodian

In the custodian “savings-only” model, you can provide customers with a secure crypto saving/investing service. This service enables customers to invest part of their savings in crypto-currencies, while you hold those investments on their behalf until they decide to withdraw. Given this model, a cold store wallet or service is mandatory to keep most crypto reserves safe.

In practice, your Nexus reserves (exchange, hot wallet, and cold store) should hold nearly the same amount you promised customers. This helps you respond quickly to withdrawal requests and avoid delays that negatively impact customer experience. In Nexus, wobble is the planned deviation from the reserve target, allowing limited spread gains. Exchange reserve is generally limited to intra-day (re)balancing requirements.

An interesting aspect is that in this model, compared to the broker one, both the buy and sell transactions (meaning the customer exchanging fiat currency for crypto-currency) are off-chain, since they are merely a bookkeeping exercise. For instance, if your customer buys 0.5 Bitcoins his/her balance will be updated accordingly, without the need for him/her to possess a digital wallet where to store them and therefore removing the need for the on-chain transactions.

What if the cumulative reserve amount is lower than the one you promise to hold for your customers? You can either choose to manually transfer the difference to one of your reserves or activate the Nexus Tradebot to automatically handle the balances according to your preferences. Both internal and external pricing can be used to adjust the balance, however it's important to note that with external pricing all transactions are executed back-to-back on the exchange.

Since this model behaves like a closed crypto system, where the source and destination addresses are the only possible trusted exchanges, the compliance risk is lower than the one of the broker model.

Custodian general schema

Account

In the custodian model, an account represents your customer's entity and may support only native or also non-native crypto. The account can be of 4 types:

  • Accounts with no addresses: Can only do off-chain transactions, it does not have a withdraw and deposit address.
  • Accounts with a send address: Can do off-chain transactions and only on-chain send transactions, it has a withdraw address (provided by Customer). The account cannot receive any crypto amount outside of Nexus but it can send to any address on the network.
  • Accounts with a receive address: Can do off-chain transactions and only on-chain receive transactions, it has a deposit address (provided by Nexus). The account cannot send any crypto amount outside of Nexus but it can receive from any address on the network.
  • Accounts that have both addresses: Can do off-chain transactions and on-chain receive/send transactions, it has a deposit address (provided by Nexus) and a withdraw address (provided by Customer), it can send and receive from/to any address on the network.

Native Accounts

An account using the native crypto of its blockchain, e.g. ETH on Ethereum.

Non-Native Accounts

An account able to use a non-native crypto on its blockchain, e.g. USDT on Ethereum, in addition to its native crypto. This requires specific setup within Nexus.

Transactions

Buy

Since there is no on-chain transaction, the change in the balance amount is merely updated in the customer's record. It is immediately created with a completed status.

Sell

The process to sell cryptocurrency in the Custodian model is off-chain transaction. It is immediately created with a completed status. The handling and use of this status can be managed within your own backend system.

ReceiveIn Transactions

A ReceiveIn is an on-chain transaction that allows a client's customer to send cryptocurrency from an external source (such as an exchange or a private wallet) to their address within Nexus.
Once the transaction is confirmed on the blockchain, the customer’s custodian balance is updated to reflect the received crypto amount.

Types of ReceiveIn Transactions

Nexus supports two types of ReceiveIn transactions:

Fixed Receive Address (Customer Account Creation)

When a new account is created with the generateReceiveAddress flag set to true, a fixed crypto address is generated for the customer.

  • Any crypto sent to this address and confirmed on the blockchain automatically increases the customer’s custodian balance by the received amount.
  • This address can be reused an unlimited number of times.

Payment Request (Single-Use Address)

Customers can generate a payment request when they wish to receive a specific or variable amount of crypto.

  • A fixed payment request specifies the exact amount to be received.
  • An open payment request allows any amount to be sent.

In both cases, Nexus creates a unique crypto address for the transaction. Once the blockchain confirms receipt, the customer’s custodian balance is updated.
Each payment request address can only be used once.

ReceiveIn Transaction Lifecycle

Because ReceiveIn is an on-chain process, the transaction lifecycle follows these steps:

  1. Initiation: The customer generates a payment request. A transaction is created in Nexus with the status Initiated. The customer then sends the crypto to the generated address.
  2. Completion: Once Nexus detects the transaction on the blockchain, the transaction status changes to Completed.
  3. Blocked: A transaction may be automatically marked as Blocked in the following cases:
    • The amount received on the blockchain does not match the requested amount.
    • Nexus detects a blockchain transaction to a unique generated customer address but cannot find a corresponding transaction record within the system.

Operator Actions for Blocked Transactions

When a transaction is marked as Blocked, Nexus provides two resolution options for the operator:

  • Re-Initiate: Changes the transaction status to Confirming, prompting Nexus to attempt to complete the transaction again.
  • Cancel: Permanently cancels the transaction to prevent further processing.

SendOut

A SendOut is an on-chain transaction where a customer transfers cryptocurrency from their Nexus address to an external destination (such as an exchange or a private wallet).

The transaction is not executed immediately. Instead, it follows a defined lifecycle:

  1. When the customer initiates a SendOut, the transaction is created in Nexus with the status Sending.
  2. Once the transaction is successfully executed and confirmed on the blockchain, its status changes to Completed.
  3. After confirmation, the customer’s custodian balance is decreased by the sent crypto amount.

The final status of a successfully processed SendOut transaction is Completed.

SendInternal

A SendInternal is an off-chain transaction where one customer can transfer crypto from their custodian wallet to another customer who also holds a custodian wallet within Nexus. Since the transfer takes place entirely within the custodian system, it does not require blockchain confirmation and is processed instantly. Once the transfer is executed, the sender’s custodian balance is decreased and the recipient’s balance is increased accordingly, with the final status marked as Completed.

Swap

A Swap is a transaction where a customer can exchange one cryptocurrency (e.g. ALGO) for another (e.g. XLM) directly within Nexus. Once the swap is executed, the customer’s balance is updated by deducting the sold asset and crediting the purchased asset, with the final status marked as Completed.

Gift

The status Gift is used when you want to reward a customer by increasing their crypto balance without reducing their fiat balance. This allows you to credit additional crypto to the customer’s custodian wallet as a bonus or reward, independent of any fiat deduction.

Clawback

The status ClawBack is used to decrease a customer’s crypto balance without increasing their fiat balance. It represents a reversal where crypto that was previously credited to the customer (for example, from a purchase) is taken back by the system.

Transactions Statuses

Each transaction in Nexus follows a defined lifecycle represented by a set of statuses.
These statuses indicate the current state of a transaction — from initiation to completion or cancellation.

Initiated

The transaction has been created in the system but not yet processed on-chain.

  • For ReceiveIn, this occurs when a customer generates a payment request.
  • For SendOut, this occurs when the customer initiates a crypto transfer request.
  • At this stage, the transaction is pending customer or system action to proceed.

Sending

The transaction has been submitted for processing and is pending blockchain confirmation.

  • Applies primarily to SendOut transactions.
  • Indicates that the transaction has been broadcast to the network but not yet confirmed.

Confirming

The transaction has been detected on the blockchain and is awaiting sufficient confirmations.

  • Commonly applies to ReceiveIn transactions after Nexus identifies the incoming crypto on-chain.
  • Once the required number of confirmations is reached, the status transitions to Completed or Blocked.

Completed

The transaction has been successfully confirmed and finalized. This is the final successful state of a transaction.

Blocked

The transaction cannot be completed automatically due to a validation or reconciliation issue.
Typical scenarios include:

  • The received amount differs from the expected amount.
  • A transaction is detected on a unique generated customer address but no corresponding record exists in Nexus.
  • Duplicate on-chain transactions (e.g., a customer sending funds twice to a single-use address).

Operators can manually review and either Re-Initiate or Cancel the transaction.

ToCancel

The transaction has been flagged for cancellation but has not yet been marked as fully Cancelled.
This is a transitional state while the system or operator completes the cancellation process.

Cancelled

The transaction has been explicitly stopped and will not proceed further.

  • The transaction is not processed on-chain.
  • No balance updates occur.
  • Represents a final state for halted transactions.

Custodian Limit

The Custodian Limit can be set per Trust Level and has the following behaviour per transaction type:

  • Buy: when the Custodian Limit is reached, the customer cannot create any more Buy transactions
  • Sell: when the Custodian Limit is reached, the customer can create Sell transactions as long as (daily/monthly/yearly/lifetime) Sell limit is not violated
  • SendInternal: when the Custodian Limit of the receiver is reached, the sender cannot create SendInternal transactions
  • ReceiveIn: ReceiveIn transactions are not affected by the Custodian Limit
  • SendOut: SendOut transactions are not affected by the Custodian Limit
  • Swap: Swap transactions are not affected by the Custodian Limit

Tradebot

Terminology and detailed explanations have been separated. You can follow the links below: