WarpCoin WARP
← All documentation

WarpCoin API Reference

WarpCoin exposes three HTTP services, each on its own port. All responses are JSON unless noted. The APIs are unauthenticated — bind them to private interfaces or front them with a reverse proxy in production.

Service Default port Started by
Node JSON-RPC 127.0.0.1:8339 warpcoin node --rpc ...
Block explorer 0.0.0.0:8340 warpcoin explorer / node --explorer ...
Market data 0.0.0.0:8341 warpcoin market

Amounts are in flux (1 WARP = 100,000,000 flux) unless a field name ends in _warp or the service documents decimal strings.

Authentication. When the node is started with --rpc-token <token> (or WARP_RPC_TOKEN), every endpoint except /healthz requires the header Authorization: Bearer <token>. The wallet/miner CLIs accept --rpc-token or read WARP_RPC_TOKEN. POST bodies are size-capped (1 MiB for transactions, 16 MiB for blocks) and all services enforce connection timeouts.

1. Node JSON-RPC (port 8339)

GET /status

Chain and network status.

{ "coin":"WarpCoin","ticker":"WARP","height":1234,"tip_hash":"…",
  "difficulty_bits":486604799,"peers":8,"mempool_size":3,
  "next_block_reward":5000000000,"mining":true,"hashes":987654321 }

GET /balance?address=<addr>

{ "address":"W…","balance":5000000000,"balance_warp":50,"nonce":2 }

GET /account?address=<addr>

Raw account: { "balance":5000000000, "nonce":2 }.

POST /tx (alias POST /send)

Submit a signed transaction (the wallet/CLI builds this). Body is a transaction object (from,to,amount,fee,nonce,timestamp,pubkey,signature).

{ "txid":"…","status":"accepted" }

GET /block?height=<h> · GET /block?hash=<h>

Returns the full block (the active tip if no parameter).

GET /mempool

{ "size":3, "transactions":[ … ] }

POST /verify

Pre-flight a transaction without broadcasting (transaction-verifier nodes).

{ "txid":"…","valid":true,"reason":"" }

GET /getwork?address=<miner-addr>

Returns a candidate block and target for external miners.

{ "block":{…}, "target":"0000ffff…", "bits":486604799, "height":1235 }

POST /submitwork

Submit a solved block (body = block with a winning header.nonce).

{ "status":"accepted","hash":"…","height":1235 }

GET /peers

{ "count":8, "connected":["1.2.3.4:8338", …], "known":[ … ] }

GET /supply

{ "ticker":"WARP","decimals":8,
  "max_flux":22999999976900000,"total_flux":2000935000000000,"circulating_flux":935000000000,
  "max_supply":229999999.769,"total_supply":20009350,"circulating_supply":9350 }

GET /healthz

{ "status":"ok","height":1234,"peers":8 }

Wallet-platform services

The node also serves the WarpCoin wallet platform — warp#tags, escrow, the merchant gateway, WarpScript contracts, and inter-planetary light-time — on the same RPC port. Privileged actions are authorized by a wallet signature over a canonical action string (digest = sha256d(utf8(action)), the same scheme as transactions), and the WarpScript compiler is byte-compatible with the web app (identical specs yield identical W… contract addresses). Full details: Wallet Platform and WarpScript Contracts.

Endpoint Method Purpose
/tag/resolve?tag= · /tag/reverse?address= GET resolve / reverse a warp#tag
/tag/register POST claim a warp#tag (signed action)
/escrow/create · /escrow/list?address= · /escrow/get?id= — open / list / fetch escrows
/escrow/action POST fund / release / refund / dispute (signed action)
/merchant/register · /merchant/get?id= — register a business / public info
/merchant/invoice/create POST create an invoice (Authorization: Bearer <apiKey>)
/merchant/invoice/get?id= · /merchant/invoices?merchantId= GET fetch / list invoices
/merchant/invoice/pay POST pay an invoice with a signed transfer (broadcast + confirm)
/contract/compile · /contract/deploy POST compile (preview) / deploy a WarpScript artifact
/contract/get?id= · /contract/list?author= GET fetch / list deployed contracts
/contract/templates · /contract/palette GET studio building blocks
/lighttime?from=&to= · /lighttime/bodies GET inter-planetary light-time + bodies

2. Block explorer (port 8340)

HTML pages: / (overview), /block/{height|hash}, /tx/{id}, /address/{addr}, /richlist, /search?q=….

JSON API

  • GET /api/stats — chain + supply summary (height, tip, difficulty, peers, mempool, total transactions, max/total/circulating supply as decimal strings).
  • GET /api/blocks?limit=20 — recent blocks (newest first).
  • GET /api/block/{height|hash} — a block.
  • GET /api/tx/{id} — { transaction, location, confirmations }.
  • GET /api/address/{addr} — { address, balance, balance_warp, nonce, tx_count, transactions:[…] }.
  • GET /api/richlist?limit=100 — top balances with reserve labels.
  • GET /api/supply — JSON supply (flux + WARP).

Supply endpoints for listing trackers

Plain-text bare decimal numbers (the format CoinGecko's Supply API expects):

GET /api/supply/circulating   ->  9350.00000000
GET /api/supply/total         ->  20009350.00000000
GET /api/supply/max           ->  229999999.76900000

Supply definitions: total = premine + mined subsidy (fees are transfers, not issuance); circulating = total minus balances still held by the genesis reserve addresses; max = premine + all future subsidy across every halving.

3. Market data API (port 8341)

A reference order book with a price-time-priority matching engine. Read APIs follow the CoinGecko and CoinMarketCap exchange-integration specs; an order API lets you place orders so the book produces real tickers and trades. Prices and amounts are decimal strings. This service does not hold funds or settle on-chain.

CoinGecko format

  • GET /api/v1/pairs — [{ "ticker_id":"WARP_USDT","base":"WARP","target":"USDT" }, …]
  • GET /api/v1/tickers — per pair: ticker_id, base_currency, target_currency, last_price, base_volume, target_volume, bid, ask, high, low.
  • GET /api/v1/orderbook?ticker_id=WARP_USDT&depth=50 — { ticker_id, timestamp, bids:[[price,amount],…], asks:[[price,amount],…] }.
  • GET /api/v1/historical_trades?ticker_id=WARP_USDT&type=buy|sell&limit=100 — { buy:[…], sell:[…] } with trade_id, price, base_volume, target_volume, trade_timestamp, type.

CoinMarketCap format

  • GET /summary — map keyed by pair with last_price, base_volume, quote_volume, lowest_ask, highest_bid, price_change_percent_24h, highest_price_24h, lowest_price_24h.
  • GET /assets — per-asset deposit/withdraw/fee metadata.
  • GET /ticker — compact per-pair ticker map.
  • GET /orderbook/{market_pair} — e.g. /orderbook/WARP_USDT.
  • GET /trades/{market_pair} — recent trades.

Order API

  • POST /api/v1/orders
    { "pair":"WARP_USDT", "side":"buy", "price":"0.10", "amount":"100" }
    Response: { "order_id":"…","status":"filled|partial|open","remaining":"…","fills":[…] }.
  • GET /api/v1/orders?pair=WARP_USDT — open (resting) orders.
  • GET /healthz — { "status":"ok","pairs":2 }.

Listing note: a tracker pulls price/volume from a market endpoint like the ones above, and supply from the explorer endpoints. See LISTING.md for the full application checklist.