NHBCoin
NHBCoin

JSON-RPC API Reference

The NHBCoin node exposes a custom JSON-RPC API. The primary RPC access point for the live network is <strong>https://api.nhbcoin.com</strong>. Public read methods (listed under Core RPC Endpoints below) can be called directly with no authentication. State-changing calls made through the Escrow Gateway require the signed-request headers described below.

View the JSON-RPC reference on GitHub

Authentication prerequisites

Every request sent through the Escrow Gateway to api.nhbcoin.com must be authenticated. Gather the following values from your developer dashboard before integrating:

  • API key (X-Api-Key): Identifies your application and maps requests to your quota.
  • Timestamp (X-Timestamp): Unix seconds generated at request time; requests outside a small window are rejected.
  • Nonce (X-Nonce): A fresh random value generated per request; reusing one is rejected as a replay.
  • HMAC signature (X-Signature): The hex-encoded HMAC-SHA256 of timestamp + nonce + METHOD + path + body (newline-joined), keyed with your API secret.
Gateway request with auth headers 
curl -X POST https://api.nhbcoin.com/escrow/create   -H "Content-Type: application/json"   -H "X-Api-Key: <YOUR_API_KEY>"   -H "X-Timestamp: 1715861103"   -H "X-Nonce: <RANDOM_NONCE>"   -H "X-Signature: <HMAC_HEX_DIGEST>"   --data '{"payer":"nhb1...","payee":"nhb1...","token":"NHB","amount":"1000000000000000000"}'

Core RPC Endpoints

nhb_getBalance

Returns the complete state of an account, including all native balances (NHB, ZapNHB, Staked) and on-chain data like the nonce and Engagement Score.

Parameters

ParameterTypeDescription
AddressstringThe nhb... address of the account to query.

Returns

An Account object.

Example Request 
curl -X POST --data '{"jsonrpc":"2.0","method":"nhb_getBalance","params":["nhb1..."],"id":1}' -H "Content-Type: application/json" http://localhost:8080
Example Response 
{"id":1,"result":{"address":"nhb1...","balanceNHB":"100000","balanceZNHB":"5000","stake":"5000","username":"alice.nhb","nonce":1,"engagementScore":5}}

nhb_sendTransaction

The universal endpoint for submitting ANY signed transaction to the network. The node's State Processor will automatically route the transaction to the correct module (Native or EVM) based on its Type field.

Parameters

ParameterTypeDescription
Signed TransactionobjectThe fully formed, signed transaction object.

Returns

A string confirming receipt by the node.

Example Request 
// This is a pseudo-code example of the JSON payload.
// The parameter is the complete, signed transaction object.
{
  "jsonrpc": "2.0",
  "method": "nhb_sendTransaction",
  "params": [{
    "type": 1,
    "nonce": 5,
    "to": "nhb1...",
    "value": "10000000000000000000",
    "gasLimit": 21000,
    "gasPrice": 1,
    "r": "0x...", "s": "0x...", "v": "0x1b"
  }],
  "id": 1
}
Example Response 
{"id":1,"result":"Transaction received by node."}

Rate limits &amp; error handling

Respect the platform-wide throttles to avoid being blacklisted. Automatic backoff keeps your payments resilient while protecting the shared infrastructure.

  • 60 requests per minute per API key on the payments Gateway.
  • HTTP 429 responses always include a Retry-After header expressed in seconds.
  • Repeated 4XX/5XX responses bubble back to your client; log the error payload for observability.
Example 429 error payload 
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Retry after 2 seconds.",
  "retryAfterSeconds": 2
}

Native Transaction Construction

Standard Transfer / EVM Call (Type 1)

To send NHBCoin, deploy a contract, or call a contract, construct a transaction with Type 1. Our State Processor automatically routes these to the integrated EVM for execution.

JavaScript Transaction Object 
// For NHB transfers, contract calls, and deployments
const evmTx = {
  type: 1, // TxTypeTransfer (delegates to EVM)
  nonce: userAccount.nonce,
  to: 'nhb1...',
  value: ethers.utils.parseEther("10.0"), // 10 NHBCoin
  gasLimit: 21000,
  gasPrice: 1,
};

Stake ZapNHB (Type 6)

Construct a transaction to lock a specified amount of liquid ZapNHB into a staked position. The amount to stake is specified in the value field.

JavaScript Transaction Object 
// To stake ZapNHB
const stakeTx = {
  type: 6, // TxTypeStake
  nonce: userAccount.nonce,
  value: ethers.utils.parseEther("5000"), // Staking 5000 ZapNHB
  gasLimit: 50000,
  gasPrice: 1,
};

Escrow Gateway (REST)

Alongside the JSON-RPC API above, a separate hosted REST surface at the same host handles escrow -- it signs and submits the underlying transactions for you, so your app never touches a private key or builds a raw transaction. See the Building with Escrow guide for full request/response shapes, the wallet-signature requirement, and webhooks.

MethodPathAuth requiredDescription
POST/escrow/createAPI key + HMAC + payer signatureCreate an escrow and get a payIntent (vault + memo) to fund it.
GET/escrow/{id}None -- public readLook up an escrow's status and event history.
POST/escrow/releaseAPI key + HMAC + payee/mediator signatureRelease a funded escrow to the payee.
POST/escrow/refundAPI key + HMAC + payer signatureRefund a funded escrow to the payer.
POST/escrow/disputeAPI key + HMAC + payer/payee signatureFlag an escrow as disputed.
POST/escrow/resolveAPI key + HMACNot yet available -- returns 503 until arbitration realms are provisioned.

The old escrow_create/escrow_release/escrow_refund/escrow_dispute/escrow_resolve JSON-RPC methods are permanently disabled (HTTP 410) -- this REST surface, not JSON-RPC, is the supported way to mutate escrow state today.

Authentication API (OAuth 2.0)

User authentication is handled by a separate, standard OAuth 2.0 REST API, not the L1's JSON-RPC. This provides a secure, seamless 'Login with NHBCoin' experience for third-party applications. See the Authenticating Users guide for the full flow.

  • GET /authorize:The initial endpoint to redirect users to for login and permission granting.
  • POST /token:The secure, backend-to-backend endpoint for exchanging an authorization code for an access token.
  • GET /userinfo:The endpoint to fetch a user's profile (address, username) using their access token.