API catalog
Every endpoint this service serves. Limits and timeouts shown are this server's current settings. The same list is at /api/catalog. How it all fits together: architecture overview.
JSON-RPC for pools
POST /rpc (or POST /) on the public listener. No login: limits apply per client (one IPv4 address or one IPv6 /64). JSON-RPC 1.0 and 2.0; replies use the request's version. Batches up to 16 requests.
getblocktemplate
The current block template from the CUSF enforcer, with the BIP300/301 commitments already in the coinbase. Always the coinbasetxn form: replace the one spendable output with your payouts and keep every other output. Use max(curtime, mintime) as the block time.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
| rules | array | no | Accepted for compatibility, e.g. ["segwit"]. Everyone gets the same template. |
| longpollid | string | no | From a previous template. Waits until the template changes (up to 30 s), then returns it. Not rate-limited; at most 8 open per client. |
| mode | string | no | "template" (default) or "proposal" (BIP23: with "data", checks a block against the enforcer's tip). |
Returns: A BIP22 template object. Without longpollid: 60 calls/min per client, burst 10.
curl -s https://gbt.bip300.xyz/rpc -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"getblocktemplate","params":[{"rules":["segwit"]}]}'
submitblock
Submit a solved block. Forwarded to the enforcer (and to bitcoind too when bitcoind.also_submit is on), matched to the template it was built from, and recorded.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
| hexdata | string | yes | The serialized block, hex. |
Returns: null when accepted, otherwise a BIP22 reject reason string. 30 calls/min per client, burst 10.
curl -s https://gbt.bip300.xyz/rpc -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"submitblock","params":["<block hex>"]}'
Service
Public listener. Open.
Whether a template can be served right now. Safe to poll: it never calls the enforcer.
Returns: 200 "ok template=<id> height=<n>", or 503 with the reason.
curl -si https://gbt.bip300.xyz/healthz
Mining overview
Public listener, next to /rpc. Open.
Everything on the Mining overview page (/): network numbers, this server's getblocktemplate URL, the public pool list from the pool registry, and resource links.
Returns: MiningData object. pools is null until the registry has been fetched.
curl -s https://gbt.bip300.xyz/api/mining
Network numbers from this server's node, recomputed every few seconds: height, last block, hashrate over 24 h and over the current retarget window, difficulty, blocks and transactions over 24 h, transactions per second over the last hour, mempool, next retarget and the expected difficulty change, last block's reward. Rates are in H/s, times in unix seconds, amounts in satoshis.
Returns: NetworkStats object, or null before the first refresh.
curl -s https://gbt.bip300.xyz/api/network
Dashboard JSON
Same listener as /rpc. Open (no login).
Chain tip, current template, upstream health and latency, BMM accepts in the current template, recent clients (addresses shortened).
Returns: OverviewData object.
curl -s https://gbt.bip300.xyz/api/overview
Template history, newest first. Repeat polls with the same content are folded into one row.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
| height | integer | no | Only templates for this block height. |
| page | integer | no | 1-based page, 50 rows per page. |
Returns: { page, page_size, total, templates: [...] }
curl -s https://gbt.bip300.xyz/api/templates?page=1
/api/templates/{id}
One template: decoded coinbase outputs, raw coinbase hex, transactions, and the diff against the previous template.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
| id | string | yes | Template id (16 hex characters), from /api/templates. |
Returns: Template detail object, or 404.
curl -s https://gbt.bip300.xyz/api/templates/<id>
Latest sidechain snapshot: each slot's status, ack progress, CTIP, withdrawal bundles and votes, recent BMM commitments, live bids.
Returns: SidechainSnapshot object, or null before the first snapshot.
curl -s https://gbt.bip300.xyz/api/sidechains
Every submitblock, newest first, with result, matched template and latency. Client addresses shortened.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
| page | integer | no | 1-based page, 50 rows per page. |
Returns: { page, page_size, total, submissions: [...] }
curl -s https://gbt.bip300.xyz/api/submissions?page=1
This catalog.
Returns: Catalog object.
curl -s https://gbt.bip300.xyz/api/catalog
Operations
Same listener as /rpc. Open (no login).
Prometheus metrics, prefixed govsrv_: upstream latency and errors, template changes by trigger, long-poll waiters, getblocktemplate calls, refusals by limit, submit results.
Returns: Prometheus text format.
curl -s https://gbt.bip300.xyz/metrics
JSON-RPC errors
Codes follow Bitcoin Core where one exists, so pool software reacts as it would to bitcoind. Errors from the enforcer itself are passed through unchanged.
| Code | Meaning |
|---|---|
| -9 | Enforcer unavailable, or its template is too old. There is no fallback template. |
| -8 | Invalid parameter (e.g. unknown mode, missing block hex). |
| -22 | Block could not be decoded. |
| -32005 | Refused by a per-client limit. The message says which one. |
| -32600 | Invalid request (e.g. missing method, empty batch). |
| -32601 | Method not found. Only getblocktemplate and submitblock are served. |
| -32700 | Body is not valid JSON. |