Quick Start

Five minutes from nothing to a confirmed transaction. All USDn on the testnet is test money.

1. Get an RPC endpoint

You have two options:

Public testnet RPC: http://165.227.236.60. It serves the standard eth_*, net_*, web3_* and nzc_* methods.
Your own node. Required if you want the key-free agent_* API, which is only served on localhost. See Run a Full Node or spin up a whole local testnet on one machine.

The examples below use http://127.0.0.1:8545; replace it with the endpoint you use.

2. Verify the chain

curl -s -X POST http://127.0.0.1:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
# {"jsonrpc":"2.0","id":1,"result":"0x5014"}   ← 20500

Chain ID 20500. Anything else is not the NetZero testnet.

3. Get test USDn

With your own node: create an agent wallet and call agent_startMining; the protocol pays USDn into it within a minute, no balance needed.
Without a node: mine against the public RPC with a few lines of Python, or ask the team for test-USDn (Testnet Status).
On a local testnet: the faucet key from cmd/nzc-testkeys holds 10,000,000 test-USDn.

Check a balance:

curl -s -X POST http://127.0.0.1:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0xYourAddress","latest"],"id":1}'

Balances are in wei: 1 USDn = 10^18.

4. Send a transaction

Python (web3.py)

pip install web3

from web3 import Web3
 
w3 = Web3(Web3.HTTPProvider("http://127.0.0.1:8545"))
assert w3.eth.chain_id == 20500
 
acct = w3.eth.account.from_key("0xYourTestPrivateKey")
tx = {
    "chainId": 20500,
    "from": acct.address,
    "to": "0xRecipient",
    "value": w3.to_wei(1, "ether"),          # 1 USDn
    "nonce": w3.eth.get_transaction_count(acct.address),
    "gas": 21000,
    "maxFeePerGas": w3.to_wei(2000, "gwei"),  # base fee floor is 1000 gwei
    "maxPriorityFeePerGas": w3.to_wei(1, "gwei"),
}
signed = acct.sign_transaction(tx)
h = w3.eth.send_raw_transaction(signed.raw_transaction)
receipt = w3.eth.wait_for_transaction_receipt(h)
print(receipt.status, receipt.blockNumber)

JavaScript (ethers v6)

npm install ethers

import { ethers } from "ethers";
 
const provider = new ethers.JsonRpcProvider("http://127.0.0.1:8545", 20500);
const wallet = new ethers.Wallet("0xYourTestPrivateKey", provider);
 
const tx = await wallet.sendTransaction({
  to: "0xRecipient",
  value: ethers.parseEther("1"),               // 1 USDn
  maxFeePerGas: ethers.parseUnits("2000", "gwei"),
  maxPriorityFeePerGas: ethers.parseUnits("1", "gwei"),
});
const receipt = await tx.wait();               // final after the next block
console.log(receipt.status, receipt.blockNumber);

Without any key at all (agent API, own node)

# create a wallet whose key never leaves the node
curl -s -X POST http://127.0.0.1:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"agent_createWallet","params":[],"id":1}'
 
# send 1 USDn from it
curl -s -X POST http://127.0.0.1:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"agent_send","params":["0xYourAgentWallet","0xRecipient","0xDE0B6B3A7640000"],"id":1}'

See the Agent API Reference.

5. What did it cost?

A transfer uses 21,000 gas. With the base fee at its floor of 1,000 gwei USDn plus a 1 gwei tip, the fee is 21,000 × 1,001 gwei = 0.021021 USDn, about two cents. Half of it, 0.0105105 USDn, was credited to the Carbon Fund in the block that included your transaction. You can verify that:

curl -s -X POST http://127.0.0.1:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x0000000000000000000000000000000000001001","latest"],"id":1}'

6. Wait for finality (optional)

Your receipt's block is final once the next block carries seven validator votes for it. Ask for the finalized head:

curl -s -X POST http://127.0.0.1:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["finalized",false],"id":1}'

If the finalized number is at or above your receipt's block number, the transaction cannot be reorganised away.