GooCoin API
Public endpoints, the three transaction broadcast modes, how to confirm a transaction, and the fair-use rules. The chain speaks standard Cosmos SDK / CometBFT — any cosmjs, cosmos-sdk or tendermint client works out of the box.
01 · Endpoints
Public endpoints
| Parameter | Value |
|---|---|
| Chain ID | goocoin-1 |
| Denom / symbol | ugoo (1 GOO = 1,000,000 ugoo) |
| REST LCD (HTTP) | https://api.goocoin.xyz |
| CometBFT JSON-RPC | https://api.goocoin.xyz/rpc |
| RPC WebSocket | wss://api.goocoin.xyz/rpc/websocket |
| Block time | ~1 s |
| Gas | free during testnet (min-gas-prices = 0ugoo) |
| Explorer | goocoin.xyz/explorer.html |
02 · Broadcast modes
Two broadcast modes
A broadcast mode is a per-request client choice. Pick it in your SDK call; the node pipeline is the same for both.
Wait for CheckTx only
The node validates the tx (signature, sequence, balance, format) and answers with the txhash and acceptance code in ~100–300 ms over the internet. Inclusion follows within ~1–2 blocks.
Use for: wallets, games, payment forms — any user-facing action where you want an immediate «accepted / rejected» answer.
How to enable: cosmjs — signAndBroadcastSync(); raw API — CometBFT RPC broadcast_tx_sync. Do not use cosmjs signAndBroadcast() in production: it holds the connection until the tx is included in a block (~2–4 s) and is not supported on the public endpoint.
Queue without waiting
The node queues the tx and answers with a hash in ~10–50 ms; validation happens in the background.
Use for: batch payouts, game item flows, server-to-server integrations — anywhere a service sends many transactions programmatically and reconciles results afterwards.
Required setup: keep a local nextSequence counter per account; set timeoutHeight (+60 blocks); after any transport error re-fetch the account sequence before resending; treat «no confirmation in ~30 blocks» as failed and retry. CometBFT RPC broadcast_tx_async.
03 · Confirming a tx
How to know a tx made it into a block
Every broadcast returns the txhash (SHA-256 of the tx bytes). Never scan blocks — look up by hash:
| Way | How | Best for |
|---|---|---|
| Poll by hash | GET /cosmos/tx/v1beta1/txs/{txhash} — 404 until included, 200 with the result after | simple clients |
| WebSocket push | subscribe on /rpc/websocket: tm.event='Tx' AND tx.hash='...' | real-time UI, explorers |
| Timeout policy | if not confirmed after ~30 blocks, treat as failed and resend with a fresh sequence | all ASYNC senders |
nextSequence counter, set timeoutHeight (e.g. +60 blocks) on every tx, and on timeout re-fetch the account sequence before resending — a stale tx that lands later simply expires.04 · Examples
Copy-paste examples
broadcast_tx_sync (raw JSON-RPC; tx is base64 TxRaw)
curl -s https://api.goocoin.xyz/rpc -X POST \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"broadcast_tx_sync",
"params":{"tx":"<base64 TxRaw>"}}'
# → {"result":{"code":0,"hash":"68E83933...","log":""}} code 0 = accepted
Check inclusion by hash
curl -s https://api.goocoin.xyz/cosmos/tx/v1beta1/txs/68E83933...
# → 404: not yet in a block · 200: {"tx_response":{"code":0,...}}
cosmjs (JS/TS)
import { SigningStargateClient, GasPrice } from "@cosmjs/stargate";
const c = await SigningStargateClient.connectWithSigner(endpoint, wallet,
{ gasPrice: GasPrice.fromString("0ugoo") });
// SYNC: returns after CheckTx — txhash + acceptance code (use this)
const r = await c.signAndBroadcastSync(addr, [msg], fee);
// then poll /cosmos/tx/v1beta1/txs/{r.transactionHash} or subscribe to ws
// NB: avoid the cosmjs default signAndBroadcast() in production — it holds
// the connection until inclusion and is not supported on the public endpoint
05 · Limits & fair use
Limits and fair use
| Control | Value / policy |
|---|---|
| Mempool capacity | 10,000 txs per node (full → new txs rejected with mempool is full, retry with backoff) |
| Invalid txs | die at CheckTx, never enter blocks or state, are not relayed to peers |
| Per-IP rate limit | nginx limit_req on the public endpoint (generous burst; see goo/deploy/nginx-api.goocoin.xyz.conf). High-volume projects: contact us for a raised quota |
| Gas fees | 0 on testnet. Mainnet: symbolic min-gas-price as the economic anti-spam filter |
06 · Scaling roadmap
When GOO gets popular
RPC nodes scale horizontally: CheckTx runs on every full node, so capacity grows linearly with nodes. Plan: regional RPC nodes behind GeoDNS (country → nearest node), health-checked, with per-project API keys at the gateway. Full write-up: repo: docs/scaling-roadmap.md.