Docs · RPC compatibility

Bitcoin-Core-Compatible RPC

Point bitcoin-cli, BTCPay, Electrum-personal-server and other Bitcoin RPC tooling at an Animica node. This mode exposes Bitcoin Core's JSON-RPC method names and response shapes (targeting Bitcoin Core 30.x) over Animica.

A compatibility layer, not an identity claim. Animica is a post-quantum, account-model, PoIES useful-work chain. This maps Bitcoin RPC meaning onto Animica so existing tooling can “point at a new endpoint” — it does not make Animica behave identically to Bitcoin.

Endpoints

Bitcoin clients POST JSON-RPC to the root path; Animica's native namespaces stay on /rpc. Both go through the same dispatcher.

POST /        ← Bitcoin-compat (bitcoin-cli, BTCPay, Electrum-personal-server, …)
POST /rpc     ← Bitcoin-compat AND native state.*/chain.*/miner.*/aicf.*

# point bitcoin-cli at an Animica node
bitcoin-cli -rpcconnect=<host> -rpcport=443 getblockcount

# or curl the public endpoint
curl -s https://mainnet.animica.org/ \
  -d '{"jsonrpc":"2.0","id":1,"method":"getblockchaininfo","params":[]}'

What's implemented

Tier 1 — read-only core

production-grade for read integrations

getblockcountgetbestblockhashgetblockhashgetblockgetblockheadergetblockchaininfogetchaintipsgetdifficultygetmempoolinfogetrawmempoolgetrawtransactionsendrawtransactiontestmempoolacceptdecoderawtransactionvalidateaddressgetnetworkinfogetpeerinfouptimestophelp

Tier 2 — wallet adapter

account-model caveats apply

getnewaddressgetbalancelistunspentsendtoaddresssendmanylisttransactionsgettransactioncreatewalletloadwalletlistwalletsbackupwallet

Tier 3 — mining

PoIES envelope under animica:*

getblocktemplatesubmitblockprioritisetransactiongeneratetoaddressgetmininginfo

How the mapping works

Bitcoin method	Animica source
getblockcount	chain.getHead().height
getbestblockhash	chain.getHead().hash (0x stripped)
getblock / getblockheader	chain.getBlockByHash → Bitcoin-shaped header/block
getrawtransaction	tx.getTransactionByHash + mempool.getRawTx
sendrawtransaction	tx.sendRawTransaction
getmempoolinfo / getrawmempool	mempool.getStats / mempool.getPending
getnetworkinfo / getpeerinfo	node.health / p2p.listPeers
getblockchaininfo	chain.getHead + chain.getChainIdentity
getblocktemplate / submitblock	miner.getBlockTemplate / miner.submitBlock

Where compatibility is degraded (by design)

Animica diverges from Bitcoin at the data-model level. These are returned as compatibility-only values so clients don't break:

Account model, not UTXO

decoderawtransaction / getrawtransaction synthesize one vin (sender, txid: null) + one vout (recipient + value). The real sender / kind / nonce / fee are carried under animica:* keys (clients ignore them).

Block height by hash

The node has no reverse hash→height index, so height is resolved only for the chain tip; deeper blocks fetched by hash report height -1 (Bitcoin's "unknown"). Block content (txs, parent, roots) is always correct.

No address-indexed history

listtransactions returns []; listunspent synthesizes one "UTXO" per address balance. Use an explorer index for history.

Synthetic difficulty

exp(thetaMicro / 1e6) — a monotonic Bitcoin-difficulty analogue (PoIES has no compact nBits target). chainwork = 00*32, bits = 1d00ffff are compatibility constants.

Single node wallet

createwallet / loadwallet are advisory; wallet_name is ignored.

stop is a no-op

Returns a string by default (the node may be the verifier seed). Set ANIMICA_BTC_COMPAT_ALLOW_STOP=1 to enable.

FAQ

Does this make Animica behave like Bitcoin?

No. It's a compatibility layer, not an identity claim. Animica is a post-quantum, account-model, PoIES useful-work chain. This mode exposes Bitcoin Core's JSON-RPC method names and response shapes (targeting Bitcoin Core 30.x) and maps their meaning onto Animica, so existing explorers, wallets, exchanges, bots, indexers and pool dashboards can point Bitcoin RPC tooling at a new endpoint.

How do hashes and units map?

Animica uses 0x+64-hex SHA3-256 hashes; responses strip 0x for Bitcoin's bare-hex convention (SHA3 vs double-SHA256 is invisible to clients). Units map nANM ↔ Bitcoin coin-unit float via /1e9 (nANM ≈ satoshi).

Which error codes are used?

Bitcoin RPC error codes: -5 (invalid address/tx), -8 (invalid parameter), -22 (deserialization), -25/-26/-27 (verify / rejected / already-in-chain), -28 (warmup), -32601 (method not found). Native Animica failures are remapped to the nearest Bitcoin code plus a reject-reason string.