Glossary
The HashNut documentation uses a set of specific terms throughout. This page defines them all in one place so the other pages don't have to repeat themselves.
Read it once end to end before your first integration, then treat it as a dictionary.
Roles
Merchant
The party accepting customer payments through HashNut — that is, you.
One chain + one wallet address = one merchant. The same wallet address on ETH and on BSC counts as two independent merchants, each with its own split wallet, api keys and orders. To go live on several chains, you set up an account on each of them separately.
Merchant channel (merchantChannel)
A grouping inside a single merchant account. The default value is default.
If several websites or apps share one split wallet, you can use channels to tell their orders apart. An order's unique key is chain + merchant address + channel + merchant order id, so the same merchant order id may be reused across different channels.
Platform
The HashNut payment gateway itself. The platform earns its fee through the share it takes at withdrawal time, and it never takes custody of merchant funds.
Agent
A third party who refers a merchant to HashNut. If a merchant is onboarded through an agent, the agent becomes a payee in the split and takes part of the platform fee. When onboarding directly, this role does not exist.
Customer
The person who places an order in the merchant's website or app and transfers funds to the receipt address.
Contracts and Addresses
Split wallet (splitter)
A smart contract the merchant deploys on chain. It is the core of the whole system and does two things:
- Claim — consolidate funds scattered across receipt addresses into itself
- Split — at withdrawal time, divide funds between the merchant, the platform (and the agent)
Deploying the split wallet is the equivalent of "opening an account" in traditional payments. One split wallet per chain is enough; receipt addresses hang off it.
Split Wallet Manager (manager)
The administrator address of the split wallet, generated jointly by the merchant's MPC Client and HashNut through the MPC protocol, with each side holding half of the key.
When the split wallet is activated, contract ownership is transferred from the merchant's wallet to the manager. From then on, administrative operations such as "register a receipt address" or "upgrade the logic contract" require both parties to sign — neither the merchant alone nor HashNut alone can execute them. This is the technical basis of HashNut's non-custodial model.
Receipt address
The address a customer actually pays into — an ordinary on-chain address (EOA). It is also generated via MPC, with the key split in two: half in your local keys.db, half at HashNut.
An order binds to exactly one receipt address; once the order finishes, the address returns to the pool and is reused by later orders.
Receipt address pool
The set of activated addresses available to orders. Creating an order takes an idle address from the pool and binds it; finishing the order (success, expiry, cancellation) releases it.
The number of addresses determines how many orders you can run concurrently — with no idle address in the pool, no new order can be created. Plan on 50 addresses for low-frequency / high-value flows and 200 for high-frequency flows.
Withdraw address (withdrawAddress)
The address that funds finally arrive at when you withdraw. It is registered when the split wallet is deployed — it is the value you type into the one-key setup screen.
WARNING
The destination of a withdrawal is the withdraw address registered at deployment, not the wallet address that sends the withdrawal transaction. Switching wallets does not change where the money goes.
Payee and share
The addresses that take part in the split are called payees — normally "merchant + platform", plus the agent when onboarded through one.
Shares always total 10000. At the default 0.8% rate, the merchant's share is 9920 and the platform's shares add up to 80.
Approve
The on-chain operation in which a receipt address grants the split wallet permission to move a given token. Without an approval, the split wallet cannot claim that token from that address.
The approved amount is fixed at the maximum uint256 value (unlimited), because claiming happens repeatedly over a long period and a finite allowance would run out quickly. Approval is tracked per (receipt address, token) — an address that should accept both USDT and USDC needs an approval for each.
Chain and token
Chains currently supported: ETH, BSC, POLYGON, TRON.
"Token" means an ERC20 / TRC20 asset on the chain; USDT is the default. Customers pay for orders in tokens.
Orders
Order
A single request for payment. The merchant creates an order → HashNut assigns a receipt address → the customer pays → HashNut confirms and notifies the merchant.
payOrderId
The order id generated by HashNut. It is globally unique and is what you use for subsequent queries, confirmations and notifications.
merchantOrderId
The order id you generate yourself and pass to HashNut when creating the order. It must be unique within a given "chain + merchant address + channel".
Order state
An integer state code from INIT(0) to FINISH(4). For the full set of values and transitions, see Order States.
The one that matters most to you is SUCCESS(3) — at that point you can fulfil the order.
expireDuration
The number of seconds from creation until the order expires; you may specify it when creating the order. It defaults to 172,800 seconds (48 hours) and may not exceed 259,200 seconds (72 hours).
An expired order cannot be resumed; its receipt address returns to the pool and you must create a new order.
Supplement order
When a customer underpays, HashNut automatically creates a supplement record for the difference. A supplement order shares the same payOrderId as the original order and can be fetched through Query Supplements.
Repeated underpayments produce several supplement orders until the cumulative amount covers the order total.
Credentials and Callbacks
api key
The credential your server uses to call the HashNut API. It comes as a pair:
| Name | Purpose |
|---|---|
accessKeyId | The public identifier, sent with each request |
secretKey | The private signing key — used only to compute signatures locally; it must never appear in a request and must never reach your front end |
One-key setup creates an api key for you automatically. A number of merchant-level settings hang off the api key as well: notifyUrl, callbackUrl, the overpay / underpay policies, the IP allowlist, and so on.
Request signature (sign)
Your server's proof of identity when calling the API, computed as Base64(HMAC-SHA256(secretKey, uuid + timestamp + request body)) and sent in request headers. HashNut signs its notifications with the same algorithm in the other direction so you can verify them. See Authentication.
accessSign
A signature string returned when the order is created and bound to that order. Order-level operations such as querying an order or confirming a payment use it as the credential, so you do not need to recompute an HMAC.
bindIp (IP allowlist)
The public IP addresses of the servers allowed to use this api key. * means no restriction. Use * while integrating and narrow it to your real server IP before going live.
notifyUrl (server-side notification)
The address HashNut calls to reach you. When an order's state changes, HashNut POSTs a notification to it.
Because HashNut is the one reaching out, this address must be reachable from the public internet.
callbackUrl (front-end redirect)
The address the customer's browser is redirected back to after paying.
Since it is only a browser redirect, it does not need to be publicly reachable — localhost works fine during local development.
DANGER
notifyUrl and callbackUrl point in opposite directions, and mixing them up is the single most common integration mistake. One way to remember it: notify is server-to-server, callback is a browser redirect. See the comparison table in Notifications.
Amounts and Fees
Order amount fields
| Field | Meaning |
|---|---|
amount | The amount due for the order |
paidAmount | The amount the customer has actually paid (including supplements) |
obtainAmount | What the merchant actually gets after the platform fee |
platformFee | The platform fee |
Rate
The platform fee, expressed in basis points of 10000. The default is 80, i.e. 0.8%.
The fee is not charged at order time; it is taken automatically by share at withdrawal time. On 1,000 USDT of revenue you withdraw 992 USDT, and 8 USDT stays in the split wallet for the platform.
Overpayment
The customer pays more than the order amount. What happens is decided by the overpay policy on the api key:
| Policy | Behavior |
|---|---|
AUTO_CONFIRM (default) | The order proceeds to confirmation and is treated as paid |
MANUAL | The order stays in its current state, awaiting manual handling |
WARNING
The excess is claimed into the split wallet along with everything else and is split by share. HashNut does not refund the difference automatically — settle any refund with the customer yourself.
Underpayment
The customer pays less than the order amount. The order stays at PAID(1) and HashNut creates a supplement order for the difference.
Whether you are notified at that point is decided by the underpay policy on the api key:
| Policy | Behavior |
|---|---|
NOTIFY (default) | Notify the merchant, so you can prompt the customer to top up |
SILENT | Do not notify; wait quietly for the top-up |
Claim
Moving funds from the receipt addresses into the split wallet. Initiated by the merchant, signed directly with the merchant wallet key.
It requires that the receipt address has already approved the token in question.
Release
Moving funds out of the split wallet to the withdraw address, also initiated by the merchant. The split happens at this step — you can only take the portion matching your share.
Gas and sweep
Every on-chain transaction costs native coin (ETH / BNB / MATIC / TRX) as gas, and it is paid entirely by the merchant's wallet — HashNut does not cover it.
Receipt addresses send their own approval transactions, so you must send a little native coin to them beforehand. Whatever is left over can be moved back to your wallet with Sweep.
Confirmations
How many subsequent blocks have confirmed a transaction. HashNut configures the required number per chain; only once it is reached does an order move from CONFIRMING(2) to SUCCESS(3). More confirmations mean less chance of a reorg, at the cost of a longer wait.
Tools
HashNut Dashboard
The browser-based merchant console (defi.hashnut.io) for creating and managing orders, maintaining api keys, configuring alert emails and so on. You sign in by signing a message with a wallet extension (MetaMask / TronLink).
HashNut MPC Client
A desktop client you run on your own PC. It handles every operation that involves a private key: deploying and activating the split wallet, creating receipt addresses, approving, claiming, releasing and sweeping.
Your private key and password stay on your machine — HashNut never stores them. The keys.db file the client creates holds your merchant wallet and MPC key shares; without it you cannot create new receipt addresses, so back it up.
One-key setup
A feature of the MPC Client that combines "deploy the split wallet → activate it → create receipt addresses → create an api key" into a single operation. See One-Key Setup.
Next
- Fund Flow — where the money goes
- Information Flow — how the order state advances and how you get notified