DIGITAL ASSET PAYMENT INFRASTRUCTURE

WEB3 PAYMENTS. BUILT FOR BUSINESS.

HashNut provides secure and efficient digital asset payment infrastructure for businesses. By simply integrating the HashNut API, businesses can start accepting digital asset payments on their websites and mobile apps.

CUSTOMER PAYS CRYPTO

MERCHANT SELF-CUSTODY

INFRASTRUCTURE DECENTRALIZED

SECURITY SMART CONTRACT

SCROLL

WHY HASHNUT

The world's first and currently the only fully decentralized Web3 enterprise digital asset payment infrastructure.

FUNDS

100% FUND SECURITY

The world's only enterprise payment system that guarantees 100% fund security.

Funds are transferred directly into merchants' self-custodied wallets, giving merchants 100% control over their assets. Its security standard exceeds that of both traditional and digital banks.

SELF-CUSTODY SMART CONTRACT MERCHANT-INITIATED 0 FUND LOSS SINCE 2022

PRIVACY

FULL PRIVACY PROTECTION

Full privacy protection for both merchants and end users.

Offers significantly stronger privacy than traditional payment systems and other crypto payment solutions.

MERCHANT PRIVACY END-USER PRIVACY FULL PRIVACY DECENTRALIZED BY DESIGN

FASTEST IN THE INDUSTRY5 MINSeamless API integration

CONTINUOUS OPERATIONS24/7No scheduled downtime or maintenance interruptions

IMMEDIATE SETTLEMENTINSTANTClearing & settlement

MAXIMIZE CASH FLOWZEROBilling cycle

LOW TRANSACTION FEES0.1%-0.9%Transaction fees

UNIVERSAL COMPATIBILITY1,000+Wallets · highest in the industry

PRODUCT IN ACTION

HashNut Payment Engine

The HashNut Payment Engine is a comprehensive distributed Web3 payment infrastructure that enables businesses to seamlessly accept cryptocurrency payments on their websites and mobile applications.

CUSTOMER Wallet · QR · Transfer

HASHNUT PAYMENT ENGINE Payment order · On-chain status

BUSINESS WORKFLOW Orders · Invoices · Logistics · Financial data

ENTERPRISE PROOF

Proprietary technology. Proven operating record.

PROPRIETARY TECHNOLOGY 74 invention patents valued at US$84 million.

74 INVENTION PATENTS

7 INTERNATIONAL PCT

US$84M INDEPENDENT VALUATION · VIGERS

OPERATING RECORD Since operations began in 2022.

100% UPTIME

0FUND LOSS

0TRANSACTION ERROR

0DATA LOSS DUE TO HACKING

ENTERPRISE ADOPTION Exclusive crypto payment system for multiple NASDAQ- and HKEX-listed companies.

Enterprise adoption proof for HashNut among NASDAQ- and HKEX-listed companies

TECHNOLOGY

How full decentralization works.

ARCHITECTURECONTROLSETTLEMENT

Smart Contract

Payment governed by fully trusted code.

SETTLEMENT CONTROL

Merchant-initiated movement.

Claim and Withdraw actions are initiated by the merchant, keeping settlement control with the business.

FUND SECURITY

No HashNut Intervention

HashNut cannot access or manage merchant funds, the architectural basis for 100% fund security.

PRIVACY

Full privacy protection.

Full privacy protection for both merchants and end users, offering significantly stronger privacy than traditional payment systems and other crypto payment solutions.

Industries

Widely applied across new-economy sectors and traditional industries.

Cloud & AI

Cloud services, AI platforms, and usage-based digital products

Subscriptions

Memberships, recurring services, and digital content

Digital Entertainment

Gaming, streaming, creator platforms, and Web3 applications

Global Commerce

Cross-border trade, e-commerce, retail, and corporate services

Travel & Events

Hotels, airlines, travel services, ticketing, and events

Financial Products

Brokerage services, RWA, CFDs, and digital-asset financial products

Explore complete industry coverage and payment scenarios.

Explore Use Cases

Bring digital asset payments into your business.

Connect your website or app through HashNut’s payment infrastructure.

CUSTOMERS PAY IN CRYPTO. YOU CONTROL FUNDS.

The HashNut Payment Engine is a comprehensive distributed Web3 payment infrastructure that enables businesses to seamlessly accept cryptocurrency payments on their websites and mobile applications.

STORE Checkout

Studio Wireless Headphones

$58.00

Total due $58.00

Credit card Visa, Mastercard

Crypto via HashNut USDT, USDC and more

PAY WITH CRYPTO 58.00 USDT

TRON

NETWORK TRON

ORDER #1042

WALLET ADDRESS TXf3q...9kLp

COPY

Confirming payment

✓Payment detectedDone

On-chain confirmationIn progress

✓

Payment complete

ORDER#1042 · PAID

AMOUNT58.00 USDT

FUNDSMerchant controlled

End users simply click Pay and complete the transaction

by scanning a QR code or transferring funds to a unique wallet address.

PRODUCT STACK

World Leading Web3 Payment for Business.

NutSDK

Robust SDK

The only solution in the world combining wholesaler, agency, and partner features in DeFi payments.

NutAuto

Quick Setup and Integration

5-min self-setup for business. Fastest in the industry.

NutDeFi

Full DeFi

World’s first and currently only full DeFi business solution. Ensures 100% security (0% hacking risk) and instant settlement.

NutConnect

Universal Compatibility

Compatible with all popular wallets, chains and token types.

NutPay

Seamless Experience

1-click payment experience comparable to WeChat, far better than other solutions.

PAYMENT COVERAGE

Accept payments globally without the need for a bank account.

Universal Compatibility

Supports virtually all major wallets, blockchains, digital assets, and central bank digital currencies (CBDCs).

₿ ₮ $

1000+WALLETS · HIGHEST IN THE INDUSTRY

TRONETHEREUMSOLANACBDC ECOSYSTEMSMORE

OPERATE

Operates 24/7

24/7CONTINUOUS OPERATION

No scheduled downtime or maintenance interruptionsContinuous payment availability.

0.1%-0.9% transaction feesTransaction fees range from 0.1% to 0.9%.

PROTECT

Full privacy protection

Merchants and end usersOffering significantly stronger privacy than traditional payment systems and other crypto payment solutions.

New client accounts can be set up in minutesClient accounts are never frozen.

PAYMENT ENGINE

A comprehensive distributed Web3 payment infrastructure.

The payment process integrates seamlessly with merchants' backend systems, synchronizing orders, invoices, logistics, and financial data to ensure a fully connected business workflow.

MERCHANTWebsite / App

CUSTOMERCrypto Wallet

HASHNUT Payment Engine

Synchronizing orders, invoices, logistics, and financial data.

BACKEND DATAOrders

BACKEND DATAInvoices

BACKEND DATALogistics

BACKEND DATAFinancial Data

FUNDS & SETTLEMENT

The world's only enterprise payment system that guarantees 100% fund security.

Funds are transferred directly into merchants' self-custodied wallets, giving merchants 100% control over their assets.

FUND PATH

PAYMENT → CONFIRMATION → CLEARING

CUSTOMER

Payment sent

The customer sends the requested digital asset from their wallet.

PAYMENT STATE

Payment confirmed

HashNut detects the transfer and returns confirmed payment status.

SETTLEMENT

Instant clearing & settlement

Zero billing cycle.

Personal wallet and card products.

NutPersonal Unified Personal Wallet

Unify all your assets under one wallet, while remaining compatible with more than 1,000 wallets and all token types.

Explore NutPersonal →

NutCard Crypto Card

The HashNut crypto card supporting Visa, UnionPay or Mastercard.

Explore NutCard →

Bring digital asset payments into your business.

Connect your website or app through HashNut’s payment infrastructure.

SEE HASHNUTIN YOUR BUSINESS.

HashNut can be widely applied across new-economy sectors and traditional industries that require digital payments and value transfer.

Try the Experience Explore Industries

Follow the payment from customer to merchant.

Choose a payment flow to see the customer checkout, on-chain verification, and the resulting merchant workflow.

Buy something and pay now.

Typical Scenarios:

CUSTOMER EXPERIENCE

9:41

HASHNUT PAYMENT ENGINE

PAYMENT ENGINE HashNut

ACTIVE

Create Request

Show QR / Address

Verify On-chain Payment

Sync Business Workflow

ON-CHAIN STATUS Awaiting transaction

REQUESTCREATED

PAYMENTDETECTED

BLOCKCONFIRMED

TX STATUSNo transaction yet

REFERENCEHN-REQ-2481

MERCHANT EXPERIENCE

Industries

Widely applied across new-economy sectors and traditional industries.

Overseas cloud services and computing platforms

VPN and network services

AI Agent services and subscription platforms

Brokerage services, security companies, and financial products, including RWA and CFDs

Overseas set-top boxes and digital content services

Online subscriptions and membership services

Online gaming and digital entertainment

Live streaming and the creator economy

Web3 and digital asset applications

Corporate services and cross-border trade

Cross-border e-commerce and global retail

Cross-border remittances

Hotels, airlines, and travel services

Ticketing and event platforms

Fitness and membership services

Restaurants and local lifestyle services

HashNut Financial Extensions.

The HashNut Payment Engine serves as the core entry point for financial activities, greatly expanding HashNut's business boundaries and profitability.

HASHNUT Payment Engine Core entry point for financial activities

Accept digital asset payments on your website or app.

Integrate the HashNut API and connect the payment flow to your business.

FULLY DECENTRALIZED. BUILT FOR ENTERPRISE.

The world's first and currently the only fully decentralized Web3 enterprise digital asset payment infrastructure.

PAYMENTCustomer Wallet

CONTROLSmart Contract

SETTLEMENTSplit Wallet

DESTINATIONMerchant Wallet

HashNutPAYMENT ENGINE

SELF-CUSTODY

Funds are transferred directly into merchants' self-custodied wallets.

CUSTOMER

Payment sent

The customer pays the receipt address assigned to the order.

RECEIPT ADDRESS

Smart Contract

The payment is managed by smart contract and lands at an address controlled by merchant.

CLAIM

Merchant starts settlement

The merchant initiates Claim to consolidate approved balances into the Split Wallet.

WITHDRAW

Funds reach the merchant

The merchant initiates Withdraw to release its available share to the configured destination.

KEY CONTROLSmart Contract

SETTLEMENT CONTROLMerchant initiated

CONTROL MODELNo unilateral HashNut control

FULL WEB3 74 INVENTION PATENTS 100% UPTIME 0.1%-0.9% TRANSACTION FEE

FULL WEB3 AND DEFI BUSINESS SOLUTION

First and currently the only true Web3 business solution.

TRANSACTION FEE

0.1%-0.9% Transaction fee

ONE-CLICK PAYMENT EXPERIENCE

YES Super Fast Integration

SELF-SETUP AND DEPLOYMENT

YES Business can deploy own contract

WHITE LABEL SOLUTION

YES Fully customizable for your brand and product experience

PROPRIETARY TECHNOLOGY

74 invention patents valued at US$84 million.

INVENTION PATENTS 74 US, Asia and other regions

INTERNATIONAL PCT 7

TOTAL VALUE US$84M Independently valued by Vigers

HIGH RELIABILITY

Since operations began in 2022.

↗Documentation

SINCE 2022

100%UPTIME

0 DowntimeContinuous operation since 2022.

FUND LOSS0NO INCIDENTS

TRANSACTION ERROR0NO INCIDENTS

DATA LOSS DUE TO HACKING0NO INCIDENTS

Bring digital asset payments into your business.

Connect your website or app through HashNut’s payment infrastructure.

WORLD'S FIRST TRUE WEB3 PAYMENT SOLUTION FOR BUSINESS.

HashNut

DIGITAL ASSET PAYMENT INFRASTRUCTURE Built for business.

EST. 2022

WEB HASHNUT.COM

WEB3PAYMENTSENTERPRISE

VISION

Web3 PayPal and beyond.

Crypto payments are growing rapidly.

CRYPTO PAYMENT US$900B 2026

2019–2026 >80% CAGR

Awards and Grants.

APAC Outstanding Application Project

Blockchainhub

Most Innovative Blockchain Project of the Year, Grand Winner.

APAC Payments Excellence Award

Grand Finalist Award.

Hong Kong ICT Awards

Gold Award, Fintech Applied Solutions. Organized by Hong Kong Government and Hong Kong Institute of Bankers.

Asia Pacific ICT Alliance Awards

Grand Award Winner: Startup of the Year. Merit Award: Business Solutions.

Cyberport Incubation Program Grant

Hong Kong Fintech Award

Outstanding Enterprise Payment Solution Award.

City University of Hong Kong

Joint internship with the School of Data Science, City University of Hong Kong.

Our Team.

TECH TEAM

WeChat Pay, Monero, and Tencent Blockchain

The technology team includes former chief architects, tech leads and senior developers from WeChat Pay, Monero, and Tencent Blockchain.

10+ years blockchain protocol development10–20 years electronic payment

COMMERCIAL TEAM

VISA Direct · CISCO · Lenovo

The commercial team includes the former Global Head of VISA Direct, a senior executive from Cisco, and a co-founder of Lenovo (Legend Computers).

100+ years collective experience in payment and tech industry

Bring digital asset payments into your business.

Connect your website or app through HashNut’s payment infrastructure.

NUTPERSONAL.

Simple DeFi wallet that unifies all your wallets. Consolidate all your personal wallets into NutPersonal.

Download on the App Store ↗ Get it on Google Play ↗

NutPersonal UNIFIED PERSONAL WALLET

1,000+ wallet compatibility ALL token types

Manage personal wallets and digital assets in one place.

NutPersonal brings payment, asset movement and wallet management into one personal experience while remaining compatible with existing wallets and assets.

Onramp / Offramp

Users and customers have the freedom to pay with either fiat or crypto. Support includes Visa, Mastercard, Google Pay, Apple Pay and more.

Swaps and Cross-chain

Pay with any token on any chain through the HashNut swaps and cross-chain infrastructure.

Nickname Payments

Make payments to a nickname instead of a blockchain address, reducing friction in everyday crypto transfers.

Cash Flow Report

Generate cash-flow reports from wallet activity so personal digital-asset movement is easier to understand.

WALLET MANAGEMENT

Consolidate wallets. Organize them into groups.

Import and consolidate personal wallets into NutPersonal to manage assets and make payments from one place.

Consolidate Wallets

NutPersonal can consolidate multiple wallets for asset management and payment.

Wallet Group

Group wallets and combine assets from different wallets when making a payment.

WALLET GROUP NutPersonal wallet group interface

Use NutPersonal for branded and partner wallet programs.

NutPersonal also supports agency structures, branded wallet experiences and connection with the HashNut Payment Engine.

MULTI-LAYER AGENCY

Manage agents and subagents.

Build a multi-layer agency system directly from NutPersonal and manage the network from one interface.

CUSTOMIZATION

Make the wallet fit your brand.

Customize the NutPersonal wallet with your business theme, logo and selected features.

HASHNUT PAYMENT

Connect personal wallet and payment.

NutPersonal works with the HashNut Payment Engine for payment and financial reporting.

WHITE LABEL

Offer it as your own wallet experience.

HashNut business and personal wallet products can be white-labelled for partners.

NutPersonal agency management interface — Agency management

Customized NutPersonal wallet interface — Customization

NutPersonal payment transfer interface — Payment experience

NutPersonal on your phone.

Download the HashNut app from the App Store or Google Play.

App Store ↗ Google Play ↗

NUTCARD.

The HashNut crypto card supporting Visa, UnionPay or Mastercard.

Apply for NutCard ↗ Contact HashNut

VISAUNIONPAYMASTERCARD

HashNutVIRTUAL

•••• •••• •••• 8241

NUTCARDCRYPTO CARD

HashNutPHYSICAL

•••• •••• •••• 5808

NUTCARDGLOBAL SPENDING

Spend cryptocurrency through card payments.

VISAUNIONPAYMASTERCARD

Multi-country and multi-currency

NutCard supports multiple countries and currencies for cross-border card use.

User-friendly KYC

NutCard uses a simplified KYC onboarding process for card users.

Partnership model

NutCard supports an agent partnership model for regional business development.

REGIONAL PARTNER BENEFITS

Join Our Partnership Program to Lead NutCard in Your Region.

NutCard provides operational tooling, partner support and commercial incentives for regional business development.

Apply for NutCard ↗

Exclusive Management Dashboard

Dedicated management dashboard to help partners efficiently manage their operations and earnings.

Enterprise-level Support

Partners can access one-on-one support for operational and commercial needs.

Lucrative Reward

Partner incentive and reward programs support regional business development.

Franchise Network

Franchise-network support is available for partners developing NutCard in their market.

Apply for NutCard.

Access the current NutCard application flow.

Apply for NutCard ↗ Contact HashNut

Welcome

HASHNUT DOCUMENTATION

Welcome to HashNut

Set up a merchant account, verify the complete fund path, integrate the payment API, and prepare HashNut for production.

Start with the payment flow

HashNut is digital asset payment infrastructure for businesses. Customers pay assigned receipt addresses on-chain. HashNut detects payment state and synchronizes it with the merchant workflow, while settlement remains under merchant control.

01Set upWallet, Dashboard, MPC Client 02VerifyPay, Claim, Withdraw 03IntegrateOrders, notifications, states 04OperateCapacity, gas, exceptions

Start with the tools

DASHBOARDHashNut Dashboard ↗

Browser-based merchant console. Sign in by signing a wallet message with MetaMask or TronLink.

LOCAL CLIENTHashNut MPC Client

Runs on Windows or macOS and handles merchant-side private-key and settlement operations locally.

GUIDED TESTDemo Shop ↗

Use the Demo Shop to verify API-key behavior and walk through an end-user payment flow.

V4 architecture

HashNut V4 uses EOA architecture with 2-of-2 MPC receipt addresses. Keep V4 account, SDK, and API materials together when implementing the current system.

V4 implementation

Use V4 merchant tooling, SDKs, and API behavior together. Do not mix V3 endpoint examples into a V4 integration.

SDK quick install

Go SDK

go get github.com/nuttybounty/hashnut-sdk-go/v4

INTRODUCTION

Glossary

The core terms used throughout HashNut setup, payment processing, settlement, and API integration.

Merchant account

One merchant wallet on one chain is one independent HashNut merchant account. Each chain has its own Split Wallet, API credentials, and receipt-address pool.

Split Wallet

The settlement contract at the center of Claim and Withdraw. Customer payments arrive at receipt addresses first, then the merchant initiates Claim to consolidate approved balances into the Split Wallet.

Receipt address

An MPC-controlled address temporarily assigned to a payment order. Customers send the requested digital asset to the receipt address shown for that order.

MPC Client

A desktop client run by the merchant. It handles wallet and MPC operations used for setup and settlement, including deployment, receipt-address creation, token approval, Claim, Withdraw, and Sweep. The merchant private key and client password stay on the merchant machine.

API key

Name	Purpose
`accessKeyId`	Public API-key identifier used by merchant-level server requests.
`secretKey`	Private HMAC signing key. Keep server-side and never expose it in frontend code.
`accessSign`	Order-bound credential returned when an order is created and used by documented order-level operations.

Order state

An integer state from INIT(0) through paid/confirmed states to FINISH(4), with negative terminal states for failure, expiry, and cancellation. SUCCESS(3) is the first safe fulfillment state.

Claim, Withdraw, Sweep

Claim consolidates approved balances from receipt addresses into the Split Wallet. Withdraw releases the merchant's available share to the configured withdrawal address. Sweep recovers leftover native gas coin from MPC-controlled receipt addresses to the merchant wallet.

GETTING STARTED

Prerequisites

Account Owner

Prepare the merchant-side tools and understand what can wait until later. Start small, verify the complete flow, then expand for production.

Provided by HashNut

Item	Purpose
HashNut MPC Client	Deploy and manage the settlement infrastructure, receipt addresses, Claim, Withdraw, and related private-key operations.
HashNut Dashboard	Create and manage orders, maintain API keys, and manage merchant settings.

What you prepare

Item	Purpose
Windows or macOS computer	Runs the HashNut MPC Client.
Merchant wallet	Pays gas and anchors one merchant account on one chain.
MetaMask or TronLink	MetaMask for supported EVM chains; TronLink for TRON Dashboard login.
Native gas coin	Enough native coin for the chain operations you will perform.
Withdrawal address	Final destination for the merchant share after Withdraw.
Application URLs	`notifyUrl` for server notifications and `callbackUrl` for browser return. These can be updated later.

The two application URLs

	notifyUrl	callbackUrl
Direction	HashNut → merchant server	Customer browser → merchant frontend
Publicly reachable?	Yes	No. Localhost can be used during local development.
Purpose	Payment-state notification	User experience / browser return
Payment proof?	Verify, then Query Order	No

Do not swap these URLs

notifyUrl is server-to-server. callbackUrl is a browser redirect. They point in opposite directions.

Setup sequence

1
Run One-Key Setup
Create the first account with 5 receipt addresses.
2
Verify the complete fund path
Create small orders, pay them, Claim, and Withdraw.
3
Verify the API key
Use the Demo Shop and API integration flow.
4
Add capacity
Increase the receipt-address pool after verification.
5
Go live
Apply production URLs, IP restrictions, monitoring, and operational ownership.

GETTING STARTED

1. One-Key Setup

Account Owner

Initialize the merchant wallet locally and create the core payment infrastructure for one merchant account on one chain.

Download and run the MPC Client

Run the client on Windows or macOS. The client is where merchant-side private-key operations happen. Keep the merchant wallet private key and MPC Client password on the merchant machine.

WindowsmacOS IntelmacOS Apple Silicon

Choose the client for your computer

Use the current V4 MPC Client release for Windows, macOS Intel, or macOS Apple Silicon. Keep the client and its local keys.db workspace together when you operate the account.

Initialize the wallet

HashNut MPC Client

Import WalletEXAMPLE

Client Password••••••••••••

Wallet TypeEVM

NetworkBSC

Private Key••••••••••••••••••

✓ Local wallet initialized

Importing the wallet creates the local MPC workspace, including keys.db. Back it up before you finish setup.

Run One-Key Setup

1
Choose the chain and merchant wallet
One chain + one merchant wallet = one independent HashNut account.
2
Set the withdrawal address
This is where the merchant share will be sent after Withdraw.
3
Start with 5 receipt addresses
Use a small receipt-address pool for verification before scaling capacity.
4
Set application URLs
notifyUrl and callbackUrl can be updated later, so temporary development values can be used while testing.
5
Run setup
The setup process creates the Split Wallet, MPC infrastructure, receipt addresses, and API credentials.

HashNut MPC Client

One-Key SetupEXAMPLE

NetworkBSC

Withdrawal Address0x72...891

Receipt Addresses5

notifyUrlhttps://merchant.example/webhook

callbackUrlhttp://localhost:3000/paid

✓ Account setup complete

Save the outputs

Save	Why
`keys.db`	Local MPC key material used by the client. Keep it backed up securely.
Merchant wallet private key	Needed independently from keys.db. Store separately.
Account Info export	Operational record of the created account and infrastructure.
`accessKeyId`	Public identifier for merchant-level API requests.
`secretKey`	Server-side HMAC signing secret. Capture and store it securely when generated.

Do not hand the merchant private key to the developer

The developer needs API credentials and account identifiers. Merchant-wallet private-key operations stay with the Account Owner / merchant-side MPC Client.

GETTING STARTED

2.2 Create and Pay an Order

Account Owner

Create a small payment order, complete the customer payment, and confirm HashNut detects it correctly.

Create the test order

HashNut Dashboard

Create OrderEXAMPLE

Amount0.01

CurrencyUSDT

Merchant AccountBSC · 0x8a...21f

Expiration48 hours

✓ Payment order created

Keep the test value small. The goal is to verify the complete path, not transaction size.

Complete the customer payment

Open the payment instructions, send the requested asset to the assigned receipt address, and wait for the order state to advance as the transaction is detected and confirmed.

TEST ORDER0.01 USDT

NetworkBSC

Receipt address0xA4...19C

Payment detected

Verify the state

Use the Dashboard and Query Order to confirm the authoritative state. Do not use the browser redirect as payment proof.

API INTEGRATION

API Quick Start

Developer

Connect the merchant server to HashNut after the account and fund path have been verified.

See the integration before writing code

Your server handles the commerce order and HashNut API. Customer funds move directly from the customer wallet to the assigned on-chain receipt address.

CREATE ORDERapplication data

Merchant AppCustomer confirms order

→

Merchant ServerCreate Order request

→

HashNutOrder + payment details

ON-CHAIN PAYMENTfund movement

Customer WalletSend configured token

→

Receipt AddressAssigned to this order

→

HashNut DetectionObserve payment + confirmations

NOTIFICATIONserver signal

HashNutPayment-state notification

→

Merchant ServerVerify + Query Order

→

Merchant AppFulfill once

The merchant server is outside the fund path. It tracks the commerce order while the customer's on-chain payment goes directly to the assigned receipt address.

Start with the account handoff

The merchant account and fund path should already be verified. The developer receives server configuration, not merchant wallet or MPC secrets.

ACCOUNT OWNER

Verified merchant account

ChainBSC

Split Wallet0x91...2AF

Fund pathVerified

→ HAND OFF accessKeyId secretKey notifyUrl callbackUrl

DEVELOPER

Merchant server

API authenticationServer-side

Order mappingPersisted

Payment stateVerified

Keep with the Account Owner merchant wallet private key MPC Client password keys.db secretKey belongs in server-side secret storage.

Server-side integration path

1
Receive the merchant account details
Use the account identifiers and API credentials created during setup. Do not receive the merchant wallet private key.
2
Store credentials securely
Keep accessKeyId and secretKey in server-side secret storage.
3
Sign merchant-level requests
Compute HMAC-SHA256 with secretKey using UUID + timestamp + request body, then Base64-encode the result.
4
Create a HashNut payment order
Map your merchant order to the returned payOrderId and accessSign.
5
Show the customer checkout
Display the amount, asset, network, and assigned receipt address.
6
Handle notifications
Verify the notification and use Query Order for the authoritative current state.
7
Fulfill once
Fulfill only after verified SUCCESS / FINISH and make the operation idempotent.

Install the Go SDK

Go SDK

go get github.com/nuttybounty/hashnut-sdk-go/v4

Do not put payment trust in the browser

Server authority

callbackUrl is a browser-return mechanism, not payment proof. Payment truth comes from verified server notification plus an authoritative Query Order result.

API reference map

EnvironmentsKeep test and production separate → Create OrderCreate and map the payment order → Query OrderRead the authoritative state → NotificationsReceive and verify state changes →

API INTEGRATION

Authentication

Developer

Sign merchant-level API requests on the server and keep the secretKey out of frontend code and client bundles.

Credential model

Credential	Use
`accessKeyId`	Public identifier for merchant-level requests.
`secretKey`	HMAC key used locally by the merchant server. Never send the secret itself.
`accessSign`	Order-bound credential returned with a created order and used by documented order-level operations.

Signing formula

Merchant request signature

sign = Base64(
  HMAC-SHA256(secretKey, uuid + timestamp + requestBody)
)

Node.js example

Illustrative signing helper

const crypto = require('node:crypto');

function signRequest(secretKey, uuid, timestamp, requestBody) {
  const input = uuid + timestamp + requestBody;
  return crypto
    .createHmac('sha256', secretKey)
    .update(input)
    .digest('base64');
}

This example implements the documented signing formula. Keep the exact request-header names and endpoint shapes aligned with the current V4 API reference.

IP allowlist

bindIp controls which server IP addresses can use an API key. * means unrestricted. It can be useful during integration, but production should be narrowed to real server IPs where applicable.

API INTEGRATION

Create Order

Developer

Create the HashNut payment order that corresponds to your own merchant order and persist the returned identifiers with your business record.

Keep your merchant order as the business record

YOUR SYSTEMMerchant Order #A1042merchantOrderId = A1042

→ Create Order →

HASHNUTPayment OrderpayOrderId + accessSign

Important fields

Field	Meaning
`merchantOrderId`	Your order identifier. Keep it unique in the relevant merchant / chain / channel context.
`merchantChannel`	Grouping inside one merchant context. Documented default value: `default`.
`expireDuration`	Order lifetime in seconds. Documented default: `172800` (48 hours); maximum: `259200` (72 hours).
`payOrderId`	HashNut globally unique payment-order identifier returned after creation.
`accessSign`	Order-bound credential returned with the payment order.

Persist the mapping

Store payOrderId and accessSign with the merchant order immediately. They are needed for order-level operations and recovery when notifications are delayed or duplicated.

API INTEGRATION

Order States

Developer / Operations

Interpret payment-order state consistently in checkout, notification handling, fulfillment, reconciliation, and operations.

State reference

Value	Name	Meaning
`0`	INIT	Order created, waiting for customer payment.
`1`	PAID	Payment transaction detected on-chain, pending confirmation.
`2`	CONFIRMING	Transaction is waiting for the required block confirmations.
`3`	SUCCESS	Payment confirmed. First safe fulfillment state.
`4`	FINISH	Post-payment processing completed; still a paid state.
`-1`	FAILED	Payment verification failed.
`-2`	EXPIRED	Order expired before payment completed.
`-3`	CANCELED	Order canceled by the merchant.

Normal paid transition

INIT 0→PAID 1→CONFIRMING 2→SUCCESS 3→FINISH 4

Underpayment

Underpayment can create supplement records for the remaining amount. Repeated partial top-ups can produce multiple supplements until cumulative payment covers the order total.

API INTEGRATION

Notifications

Developer

Receive payment-state changes server-to-server, verify them, and then query the authoritative order state before fulfillment.

notifyUrl and callbackUrl are different channels

	notifyUrl	callbackUrl
Direction	HashNut → merchant server	Customer browser → merchant frontend
Reachability	Must be reachable by HashNut	Can be localhost during development
Purpose	Payment-state signal	Return customer to merchant experience
Payment proof	Verify, then Query Order	Never use as proof

Notification handling pattern

1
Receive
Accept the server-to-server notification at notifyUrl.
2
Verify
Verify the HashNut signature using the documented signing algorithm.
3
Map
Locate the merchant order using the HashNut / merchant identifiers.
4
Query
Call Query Order for the authoritative current state.
5
Fulfill once
Fulfill only at a verified safe paid state and make the operation idempotent.
6
Acknowledge
Return the response expected by the current V4 notification contract.

Documented webhook states

Current local reference material documents notifications for PAID, SUCCESS, FAILED, and EXPIRED. Do not assume every state transition generates a notification.

API INTEGRATION

Error Handling

Developer

Design the integration so delayed notifications, duplicate events, partial payment, expiration, and temporary API failures do not create duplicate fulfillment or lost orders.

Build for recovery

Situation	Response
Duplicate notification	Make notification processing and fulfillment idempotent.
Missing / delayed notification	Query Order by `payOrderId + accessSign`.
Browser returns before notification	Do not trust callbackUrl; query the server-side order state.
Underpayment	Handle supplement records / remaining amount according to the configured policy.
Expired order	Create a new order. Do not try to resume an expired one.
Temporary API failure	Retry with bounded backoff and keep the merchant order pending rather than fulfilling optimistically.

Operational visibility

Log merchantOrderId, payOrderId, order state, notification receipt time, Query Order result, and fulfillment outcome. Do not log secretKey or merchant private keys.

OPERATIONS

Operations Overview

Operations

After launch, keep payment processing healthy by watching order states, settlement, capacity, native gas, and exceptions.

Read the operating picture

Operations does not need to inspect application code to answer the four questions that keep live payments healthy.

01Live orders

What state are payments in?

INIT · PAID · CONFIRMING · SUCCESS · FINISH

02Funds

What is ready to collect?

Receipt balances · Claim · Withdraw

03Capacity

Are idle receipt addresses available?

Open orders · Available addresses · Gas

04Exceptions

What needs a person?

State mismatch · Gas · Capacity · Reconciliation

Observe orders→ Collect funds→ Withdraw→ Protect capacity & gas→ Reconcile exceptions

Daily operating loop

Observe→Orders→Claim→Withdraw→Capacity→Gas→Exceptions

Responsibilities

Area	Primary owner
Customer/order-state issues	Operations + Developer
Claim / Withdraw	Account Owner / authorized Operations
Receipt-address capacity	Operations
Native gas	Operations / Account Owner
API authentication / notification failures	Developer
keys.db / merchant wallet backup	Account Owner

OPERATIONS

Live Orders

Operations

Monitor open and recently paid orders by state, investigate outliers, and use Query Order when a merchant system and HashNut appear out of sync.

States to watch

State	Operational meaning
INIT	Order is open and waiting for customer payment.
PAID / CONFIRMING	Payment detected but not yet at the first safe fulfillment state.
SUCCESS	Payment confirmed. Application may fulfill once after authoritative verification.
FINISH	Later paid state / post-processing complete.
FAILED / EXPIRED / CANCELED	Terminal exceptions requiring merchant-side handling rather than fulfillment.

Reconciliation fields

Keep merchantOrderId, payOrderId, current state, paid amount, timestamps, and fulfillment status searchable in the merchant system.

OPERATIONS

Capacity & Gas

Operations

Keep enough receipt-address capacity for open orders and enough native gas for merchant-side on-chain operations.

Receipt-address capacity

Receipt addresses are reused across orders, but an address assigned to an active order is not available for another active order. Monitor remaining capacity before demand consumes the pool.

Scale with payment frequency

Current public guidance recommends 5 addresses for initial verification, then production pools sized in practical multiples such as 50, 100, or 200. Choose capacity based on concurrent open-order demand rather than total historical transaction count.

Native gas

Chain family	Merchant-side gas
Ethereum / EVM	Native network coin required for relevant deployment and on-chain merchant operations.
BSC	BNB
Polygon	POL / current native network coin
TRON	TRX

Do not wait for an operational action to fail before topping up gas. Include native balance in the operating checklist.

OPERATIONS

Exceptions & Health

Operations

Detect problems early, separate payment-state issues from settlement issues, and escalate with enough context for the right owner to act.

Common exception classes

Symptom	Likely owner / first check
Order remains INIT after customer says they paid	Check chain transaction, network/asset, receipt address, then Developer / HashNut payment detection.
Order PAID / CONFIRMING for unusually long	Check chain confirmations and network health.
Notification missing	Developer queries order directly and checks notifyUrl reachability / logs.
Claim cannot collect token	Check token approval and receipt-address balance.
Withdraw destination unexpected	Stop and verify configured withdrawal address before retrying.
Receipt pool running low	Operations adds capacity before open orders consume the pool.
MPC Client cannot create new addresses	Check local client, keys.db, merchant wallet, network, and gas.

Escalation packet

Include merchant account / chain, merchantOrderId, payOrderId, current order state, transaction hash if applicable, timestamps, operation attempted, and the exact error. Never send secretKey or private keys.

SDK

Go SDK

Developer

Use the V4 Go SDK when your backend is written in Go.

Install

Go SDK

go get github.com/nuttybounty/hashnut-sdk-go/v4

Server responsibilities

The SDK can reduce request-building work, but your server still owns credential security, merchant-order mapping, notification verification, authoritative order queries, idempotent fulfillment, and operational logging.

Use V4 package paths

Use V4 package paths and V4 API behavior together. Do not mix V3 endpoint examples into the integration.

REFERENCE

Backup & Recovery

Back up the merchant-side assets that are required to continue operating the account and keep server credentials separate from wallet secrets.

Protect two different sets of operating data

Local MPC material and account information serve different purposes. Store both, but keep wallet secrets and application credentials separated.

LOCAL

`keys.db`

Local MPC key material used by the merchant-side client.

Store with MPC Client workspace Protect as merchant-side secret material If lost existing on-chain infrastructure still exists, but local MPC operations cannot continue from that workspace

ACCOUNT

Account Info

Configuration and identifiers needed to understand and integrate the merchant account.

ChainBSC

Split Wallet0x91...2AF

Withdrawal0x72...891

accessKeyIdAKID••••91

secretKey••••••••••••

Merchant-sidewallet private key · MPC password · keys.db

≠

Application serveraccessKeyId · secretKey · API configuration

What to back up

Asset	Rule
`keys.db`	Back up securely. Required by the local MPC Client workspace for continuing MPC-controlled address operations.
Merchant wallet private key	Back up separately from keys.db. Do not give it to the developer.
Account Info	Keep the exported account record with merchant operational documentation.
`accessKeyId`	Store in server configuration.
`secretKey`	Store in server-side secret storage and capture it securely when generated.

Separation

The Account Owner protects merchant wallet material and local MPC assets. The Developer protects application API secrets. These responsibilities may belong to the same person in a small team, but the secrets should still be stored and handled separately.

API REFERENCE

Configuration

Developer

Keep merchant payment behavior and application routing explicit, editable, and production-safe.

Application URLs

Setting	Meaning
`notifyUrl`	Public server endpoint that receives HashNut payment-state notifications.
`callbackUrl`	Browser return URL after the customer payment experience. Can be localhost during local development.
`bindIp`	Server IP allowlist for the API key. `*` means unrestricted.

Order defaults

Setting	Documented behavior
`merchantChannel`	Default channel value documented as `default`.
`expireDuration`	Default 172800 seconds (48 hours), maximum 259200 seconds (72 hours).
Receipt capacity	Start small for verification; scale after the account and integration are proven.

Before go-live

Before go-live, confirm production URLs, IP restrictions, withdrawal destination, capacity, gas, notification handling, and operational ownership. Configuration changes should be recorded and tested before meaningful payment volume reaches the account.

Try HashNut live.

Buy one demo item with 0.01 USDT. After the payment is confirmed, take over the same order as the merchant and complete the settlement.

CUSTOMER · STORE

Bring digital asset payments into your business.

Connect your website or app through HashNut’s payment infrastructure.

Open Dashboard ↗ Documentation

START THE CONVERSATION.

Tell us about your payment use case, distribution opportunity, or strategic partnership.

LEGAL

Privacy Policy.

How HashNut collects, uses, shares, and manages information when you use the Services.

Loading Privacy Policy…

LEGAL

Terms of Use.

The terms governing access to and use of HashNut websites, applications, products, and services.

Loading Terms of Use…

LEGAL

Information Security Policy.

How HashNut protects information, systems, and data across its technology and operations.

Loading Information Security Policy…

LEGAL

AML / CTF Policy.

How HashNut identifies, assesses, and manages financial crime risk across its business.

Loading AML / CTF Policy…