Deposit Addresses

A deposit address is a destination for receiving assets from an external wallet or exchange into an OOLIN account. In a customer wallet, select an asset and network, allocate a destination for that combination, and display it to the customer. The customer sends funds on the displayed network, then your service tracks the deposit transaction.

Accounts, addresses, and deposit transactions

An account owns balances and transactions, a deposit address provides an external receiving destination, and a deposit transaction represents an actual transfer and its processing result.

Customer USER account
  → select the asset type and network
  → allocate a destination: address + required memo
  → customer sends funds externally
  → discover the deposit and confirm completion
  → credit that account's asset balance

Identifier or field	Meaning	Used for
account_id	Receiving account	Address allocation/listing and balance queries
address_id	Allocated destination record	Persisting and distinguishing destinations
asset_type_id	Asset type to receive	Selecting supported assets
network_id	Transfer network	Network selection and display
address	External receiving address	The address entered in the customer's sending interface
tag_or_memo	Additional destination information when required	A tag or memo entered alongside the address
deposit_id	An actual deposit transaction	Tracking deposit state and completion

address_id and deposit_id identify different resources. A destination can receive multiple transfers, so persist the destination separately from individual deposits. Allocation prepares the destination; verify balance credit after an actual deposit completes.

Select the asset and network together

Allocate a destination by account_id, asset_type_id, and network_id. For multiple assets or networks on one account, verify each supported combination and its allocation result.

For example, receiving USDT on Ethereum Sepolia requires selecting the USDT asset type and Sepolia network, verifying the asset is active, and allocating its destination. Sending ETH to the same address does not fund the USDT balance. Display both the asset and network in deposit instructions.

Different asset/network combinations on one account can return the same address string. Matching address text alone does not establish asset support or network identity; use the account, asset, and network returned with the destination. Do not assume each network always receives a different address.

Group networks into mainnets and testnets on the deposit screen and label the selected destination, for example Ethereum Mainnet · Mainnet or Ethereum Sepolia · Testnet. See Supported Networks for the catalog and expansion guidance.

Allocation and retrieval

Task	API	What to verify
Allocate a destination	POST /accounts/{account_id}/deposit-addresses	Request body asset_type_id and network_id
List allocated destinations	GET /accounts/{account_id}/deposit-addresses	Account, asset, network, address, and memo in data.items

Send both request IDs as JSON numbers. Responses provide asset_type_id and network_id as strings; follow the API Reference for request and response types.

Prepare a wallet's deposit screen in this order:

1. Verify the mapped customer account and selected asset/network.
2. Check stored allocation data or the destination list for that combination.
3. Allocate a destination if the required combination is absent.
4. Persist the successful response's address_id, address, asset, network, and memo together.
5. Display the destination matching the customer's selected asset/network.

List queries use page and page_size and return the most recently created destinations first. When multiple destinations exist, check the required asset/network rather than choosing the first item automatically, and retrieve subsequent pages as needed.

If the allocation response is lost, query the destination list first. Repeating allocation does not necessarily return a new address string, so do not use it as an address rotation mechanism. Resolve allocation errors before displaying a destination to the customer.

Addresses and tags or memos

A destination includes an address, a network, and a tag or memo when required. If tag_or_memo is provided, display it so the customer can copy and enter it separately. A null response means no additional value was provided for that destination.

Interface field	Information
Asset	The name/code the customer should send
Network	The network associated with the allocation
Address	The full returned address with a copy action
Tag / Memo	Any value to enter alongside the address

Saving or copying only the address can omit the network and memo. When providing QR codes or external app links, also let customers verify the asset/network and required memo.

Confirm deposits after allocation

When a customer sends 100 USDT, confirm the transfer through the deposit API. Persist the discovered deposit_id and mark funding complete at status: COMPLETED. Query balances and ledger entries to verify the credited amount.

Deposit addresses differ from the unit used to query balances. An account can have multiple destinations while balances are queried by account_id and asset_type_id. See Deposit Flow for tracking and Balances and Ledger for accounting records.

Business wallets and payments

A business account receiving assets externally also uses a destination for the selected account, asset, and network. In Digital Payment, customers use deposit addresses to fund their wallets, then make internal payments using the merchant's recipient account ID. Receiving an internal transfer does not require entering an external address.

See Issue a Deposit Address for allocation/retrieval code, Users, Accounts, and Wallets for ownership, and Networks and Assets for supported combinations.