1. Wallet as a Service(WaaS)
Bitycle Business
English
  • English
  • Turkish
  • Getting started
  • Bitycle Widget
    • introduction
    • demo
    • widgets
      • Advance Chart
      • Full Chart
      • Overview Chart
      • Fear & Greed
      • Technical Analysis
      • Mini Chart
      • Trends
      • Compare
      • Treemap
      • Ticker
      • Digest(AI)
      • News
      • Info
  • Bitycle Lab
    • Introduction
    • Wallet as a Service(WaaS)
      • Introduction
      • Quick start
      • Concepts
      • Callbacks
      • Errors & FAQ
      • Buy TRON Energy & Bandwidth
      • Tokens List
        GET
      • Get Balance
        GET
      • Request Ramzlink
        POST
      • Callback New Payment
        POST
      • Get Ramzlink Status
        GET
      • Request Wallet (VIP)
        POST
      • Inquiry payment
        POST
      • Request Withdrawal
        POST
      • Get single Withdrawal
        GET
      • Get Deposits
        GET
      • Get Withdrawals
        GET
    • Blockchain Indexer
      • introduction
      • Blockchain List
      • Contract Info
      • Get Balances
    • Security&Privacy
      • introduction
      • Check Blocked Wallets
      • Add to watch list
      • Get watch list
      • Delete from watch list
      • Get address label
      • Get address information
    • Node as a Service(NaaS)
      • introduction
    • Tokenization
      • introduction
    • Decentralized Storage(IPFS)
      • introduction
    • Hyperledger Services
      • introduction
  • Bitycle Cap
    • introduction
    • Coins
      • introduction
      • Coin List
      • Coin Info
      • Coin Price
      • coin exchange listings
    • Markets
      • introduction
      • Market Price
      • Markets Price
      • Markets List
      • Markets frame info
      • market sparklines
    • exchanges
      • introduction
      • CEX Aggregator(Buy&Sell)
        • introduction
        • get tradable markets
        • get tradable markets price
        • send otc order
        • get orders
        • get balances
      • Exchanges List
      • Exchange Info
      • Exchange Coins Listing
      • Exchange Markets Listing
  • Schemas
    • wallet
  1. Wallet as a Service(WaaS)

Concepts

The words and rules used across the WaaS API. New here? Start with the Quick start.

Base URL and format#

Base URL: https://chainhub.bitycle.com
Request and response bodies are JSON (Content-Type: application/json).
Amounts are strings with 8 decimals ("500.00000000"), times are UTC in ISO 8601 ("2026-11-15T10:35:26.000Z").
Token symbols are upper case and case-sensitive: USDT, not usdt.

Authentication#

WhatWhere to find itUsed for
Merchant codeDashboard → Profile → Gateway Setting → Payment GateWay (Merchant Code)Every request except Tokens List and Get Ramzlink Status: header Authorization: Token YOUR_MERCHANT_CODE
API key + secret key (VIP)Dashboard → Profile → Gateway Setting → API Key InformationRequest Withdrawal: headers x-api-key, x-timestamp, x-signature (HMAC-SHA256)
Server IP (optional)Dashboard → Profile → Gateway Setting → Server IpWhen set, address, inquiry and withdrawal requests from any other IP are rejected
All three are server-side secrets: never put them in a mobile app, a web page or a public repository.

Your balance#

You have one balance per token (see Get Balance).
A deposit adds amount - fee as soon as it is credited (before the callback is sent).
A withdrawal takes its full amount when it is registered; the receiver gets amount - fee. A cancelled withdrawal gives the amount back.

Terminals (VIP)#

A terminal is one permanent set of deposit addresses, identified by a number called nounce in requests and terminalId in callbacks and inquiries.
A VIP account gets a range of 100,000 terminals, shown in Gateway Setting (Terminal (Nonce) Start / End, e.g. 300000–399999). Numbers outside it are rejected (TerminalId is not valid.).
Give one terminal to each of your users and store it with the user. The addresses never change, and they stay watched forever, so a terminal must never be given to another user.
A terminal has one EVM address, the same on every EVM network we support (BSC, Ethereum, Polygon, Arbitrum, Optimism, Avax, Sonic), and one Tron address.
Every supported token sent to it is credited, whatever token you asked for in Request Wallet.
Calling Request Wallet again for a terminal is safe: same addresses, and it replaces the terminal's callback_url and description.
Ramzlink invoices use temporary terminals of their own; you only see them as terminalId in Get Deposits.

Ramzlink invoices#

An invoice is a hosted payment page for one amount in one token.
The page shows a 2-hour timer (expirationTime), but deposits that arrive up to 24 hours after creation are still credited and counted.
The customer can pay in several parts; the invoice is paid (SUCCESS) when total_deposits reaches required_amount.
Only the invoice's token is credited automatically.

trxRefId: the transaction hash#

trxRefId (callbacks, Inquiry) and trx_hash (lists, invoices) are the blockchain transaction hash of the deposit: 0x… (66 characters) on EVM networks, 64 hex characters without 0x on Tron. You can look it up in any block explorer.
One credit per transaction: if a single transaction sends tokens to several of your addresses (some batch payouts do), only the first transfer is credited automatically. Contact support with the hash for the others.

Networks and tokens#

Tokens List is the source of truth: for each token, the networks where it can be deposited (allow_deposit) and withdrawn (allow_withdraw), and the fees. A network's name (BSC, Tron, Ethereum, …) is the value used in deposits (network, chainName) and in withdrawals (chain).
The addresses list from Request Wallet already contains only the networks where that token can be deposited. Show your users that list, not a fixed one.

Fees#

Deposit fee: a percentage of each deposit (your account's rate), with a minimum and a maximum per token and network. The minimum is min_deposit_fee in Tokens List and minDeposit next to each address. A deposit of the minimum or less is taken completely as fee and credits 0. Tell your users to send more than minDeposit.
Withdrawal fee: a fixed amount per token and network, withdraw_fee in Tokens List.
Each deposit's fee is in Inquiry and Get Deposits; each withdrawal's in Get single Withdrawal.

Statuses#

Deposits (Inquiry, Get Deposits)
StatusMeaning
PENDINGAddress created, nothing received yet
SUCCESSCredited
INSUFFICIENT_PENDINGRamzlink: credited, invoice not fully paid yet
INSUFFICIENTRamzlink: credited, invoice ended not fully paid
FAILRamzlink: nothing received within 24 hours
Ramzlink invoices (Get Ramzlink Status, Ramzlink callback): PENDING, INSUFFICIENT_PENDING, SUCCESS (paid), INSUFFICIENT, FAIL; see Get Ramzlink Status.
Withdrawals
StatusMeaning
PENDINGRegistered, waiting to be paid (can still be cancelled in the dashboard)
ACCEPTEDBeing paid on chain
SUCCESSPaid; trx_hash is the transaction
FAILNot paid; contact support
CANCELLEDCancelled; the amount is back in your balance

Timing#

A deposit is credited once its transaction is in a block and our tracker has read that block, usually within a few minutes. The callback is sent right after that. Withdrawals are paid on chain in regular batches, usually within minutes.

Limits#

WhatLimit
Request Wallet (VIP), Inquiry60 requests per minute
Request RamzlinkA daily limit may be set on your account (HTTP 429)
Lists (Get Deposits, Get Withdrawals)Up to 25 rows per page
Send callback again in the dashboard5 per minute
Modified at 2026-11-18 05:48:25
Previous
Quick start
Next
Callbacks
Built with