JSON-RPC API reference.

01 The transport

GCC is a Litecoin Core v0.21.5.5 fork, so its control interface is the Bitcoin/Litecoin Core JSON-RPC API, unchanged. If you have written code against bitcoind or litecoind, it will talk to gccd with nothing more than a different port and different credentials. Every method, parameter and result shape on this page is the upstream Core behaviour — this reference simply pins down the ones an operator of the demo chain actually reaches for, with GCC-specific values (port 9332, gcc1… addresses, 50 GCC reward, 60-second blocks) baked into the examples.

The wire format is JSON-RPC 1.0 over HTTP. You POST a JSON body to the node’s RPC endpoint; the node replies with a JSON object carrying result, error and id. A request body has four fields:

• jsonrpc — the string "1.0".
• id — any value you choose; echoed back so you can match replies to requests.
• method — the RPC method name, e.g. "getblockcount".
• params — an array of positional arguments (empty array if the method takes none).

The endpoint is http://127.0.0.1:9332/ for node-level calls. Wallet calls go to a wallet-scoped path, http://127.0.0.1:9332/wallet/<walletname>, because a node can load several wallets at once — more on that in section 04.

02 Authentication and the curl pattern

The RPC uses HTTP Basic authentication. The username and password are the rpcuser/rpcpassword you set in gcc.conf (or a rpcauth salted hash). curl sends them with --user user:pass. The canonical shape of every call on this page is:

Substitute the method, fill in params, and point the path at /wallet/<name> for wallet methods. For readability the examples below show the JSON body and a trimmed result; in practice you would pipe the response through jq to pretty-print it. The equivalent gcc-cli form is always gcc-cli METHOD arg1 arg2 … and is quicker for interactive use — the raw curl form is what you embed in scripts and services.

03 Blockchain methods

These read chain state. They are wallet-independent, so they go to the bare / endpoint.

getblockchaininfo — overall chain status: name, height, best hash, difficulty, verification progress. The single best health check for a node.

getblockcount — the height of the most-work chain tip, as a bare integer. Cheap; safe to poll.

getblockhash — the block hash at a given height. Params: [height]. Use it to turn a height into a hash you can then pass to getblock.

getblock — a block’s contents. Params: [blockhash, verbosity]. Verbosity 1 (default) returns a decoded header plus the list of txids; verbosity 2 additionally decodes every transaction; verbosity 0 returns the raw serialised hex.

getblocktemplate — the assembled candidate a miner works on: target, height, the transactions to include and the coinbase value. This is the method a stratum pool calls to build work; for GCC it returns Scrypt-targeted parameters. Params take a capabilities object, e.g. [{"rules":["segwit"]}].

coinbasevalue is in the smallest unit (1 GCC = 100,000,000 base units), so 5000000000 is the 50 GCC block reward before any fees.

04 Wallet methods

Wallet methods touch keys and funds, so they are addressed to a wallet-scoped path: http://127.0.0.1:9332/wallet/<walletname>. The default wallet is often just "" (the empty name), in which case the path is /wallet/. A node can hold several wallets — miner, faucet, a per-tenant wallet — and the path selects which one the call operates on.

getnewaddress — derive a fresh receiving address. Params: [label, address_type]. For GCC, address_type may be bech32 (native SegWit, gcc1…), p2sh-segwit, or legacy (G…). bech32 is the default and what the wallet uses.

getbalance — the confirmed, spendable balance of the wallet, as a number in GCC. Remember coinbase outputs are not spendable until 100 confirmations; immature rewards do not count here.

listunspent — the wallet’s spendable outputs (UTXOs). Params: [minconf, maxconf, [addresses]]. Each entry carries the txid, vout, address, amount and confirmation count — this is what you read to build a transaction by hand or to audit what the wallet can spend.

sendtoaddress — build, sign and broadcast a payment in one call. Params: [address, amount, comment]. Returns the txid. The amount is in GCC. The wallet selects inputs and a change output for you.

This is exactly how the GCC faucet pays a claim: a sendtoaddress from the faucet wallet to the address the claimant supplied. The returned txid is what the explorer then shows.

generatetoaddress — mine N blocks to an address (private/regtest networks only). Params: [nblocks, address]. Covered in depth on the Running a testnet node page; the call shape:

05 Network and mining methods

getmininginfo — mining-side view: current height, difficulty, network hashrate estimate and mempool size. Useful for a pool or a dashboard.

getnetworkinfo — the node’s networking state: protocol version, subversion string, connection count and the local addresses it is advertising.

The subversion carries the GCC fork identity; connections is your peer count — 0 on a node with addnode set points at a P2P-port reachability problem on 9433.

submitblock — submit a fully-solved block for validation and propagation. Params: [hexdata]. This is the other half of the mining loop: a miner gets work from getblocktemplate, finds a nonce that satisfies the Scrypt target, serialises the block and submits it here. A null result means accepted; a string result is the rejection reason.

A result of null here is success — the block was accepted onto the chain. If you instead see "high-hash", the submitted block’s Scrypt hash did not meet the target; "duplicate" means that block is already known.

06 Errors and batching

When a call fails, result is null and error is an object with a numeric code and a message:

Codes you will meet often: -8 (invalid parameter), -5 (invalid address or key), -6 (insufficient funds), -32601 (method not found — usually a typo or a wallet method sent to the bare / path), and -28 (the node is still warming up / in initial block download — back off and retry). An HTTP 401 means the Basic-auth credentials were wrong, before the JSON layer was even reached.

You can also send a batch: an array of request objects in one POST. The node returns an array of replies, matched by id. Useful when a dashboard needs height, difficulty and peer count together:

07 Security

The RPC is the keys to the chain. Hold these rules:

• Loopback only. rpcbind=127.0.0.1, rpcallowip=127.0.0.1, and a 127.0.0.1:9332:9332 Docker publish. Never bind to 0.0.0.0 and never widen rpcallowip to the open internet. If a remote service needs RPC, tunnel it over SSH rather than exposing the port.
• Strong, rotated credentials. Use a long random rpcpassword or the rpcauth salted hash so no plaintext sits in the config. Rotate immediately if a credential is printed to a log, committed, or shared. Keep --user user:pass out of shell history and process lists.
• Per-service least privilege. Give a faucet service its own wallet (/wallet/faucet) with only the funds it needs, not the miner wallet. The path scoping is your blast-radius control.
• Firewall behind the bind. On the reference stack the host firewall DROPs the RPC port for any non-operator source, so a configuration slip cannot open it to the world. Do the same.