Skip to content

COINSET_DOCS_AND_API.md

Latest commit

 

History

History
256 lines (204 loc) · 11.6 KB

COINSET_DOCS_AND_API.md

File metadata and controls

256 lines (204 loc) · 11.6 KB

Coinset Docs & API Reference

Status

This file is kept as a local snapshot/reference and should not be removed. Use it for offline notes and endpoint quick-lookups, but treat the Coinset CLI skill as the canonical operator workflow reference:

For repo-specific execution and host validation, use:

  • docs/coinset-validation.md
  • scripts/probe_coinset_capabilities.py

This file summarizes the public docs currently available from https://www.coinset.org/docs and linked usage pages.

As of: 2026-02-19

Overview

  • Coinset positions itself as a free, fast, reliable Chia blockchain API service.
  • Mainnet API base URL: https://api.coinset.org.
  • Testnet11 base URL: https://testnet11.api.coinset.org.
  • Most documented endpoints use POST + JSON body.
  • Real-time updates are documented via WebSocket at wss://coinset.org/ws.
  • Docs site is hosted separately at https://www.coinset.org/docs.

Network Routing (Explicit)

Use these exact hosts:

# Docs
curl https://www.coinset.org/docs

# Mainnet API
curl https://api.coinset.org

# Testnet API
curl https://testnet11.api.coinset.org

Docs Structure (Observed)

  • Introduction: https://www.coinset.org/docs
  • Endpoint categories observed:
    • usage/blocks
    • usage/coins
    • usage/fees
    • usage/full--node
    • usage/mempool
    • usage/web-socket

API Conventions

  • Typical response envelope:
    • success (boolean)
    • error (string)
    • plus endpoint-specific payload keys
  • Hash-like fields are usually documented as hex strings (for example header_hash, coin_id, tx_id).
  • In live responses, some numeric fields may appear as:
    • integers
    • decimal strings
    • hex strings (0x...)
    • occasionally bare 0x for zero-like values
  • Some fields that are semantically numeric/opcode-like may appear as either strings or integers.
  • Common optional filters on coin queries:
    • start_height (uint32)
    • end_height (uint32)
    • include_spent_coins (boolean)

Endpoint Catalog (Verified)

Blocks

  • POST /get_additions_and_removals - block additions/removals by header_hash
  • POST /get_block - full block by header_hash
  • POST /get_block_count_metrics - aggregate block metrics (compact_blocks, uncompact_blocks, hint_count)
  • POST /get_block_record - block record by header_hash
  • POST /get_block_record_by_height - block record by height
  • POST /get_block_records - block records in [start, end]
  • POST /get_block_spends - spends in block by header_hash
  • POST /get_block_spends_with_conditions - spends + conditions by header_hash
  • POST /get_blocks - blocks in [start, end] with optional exclude_header_hash, exclude_reorged
  • POST /get_unfinished_block_headers - unfinished block headers (empty body)

Fee Analysis Notes (Block + Spend Level)

  • get_blocks exposes block-level fee totals via transactions_info.fees.
  • For spend-level inspection, use get_block_spends_with_conditions.
  • A practical spend-fee estimator is:
    • coin_spend.coin.amount - sum(CREATE_COIN output amounts)
  • In practice, get_blocks payloads can occasionally omit header_hash; if needed, resolve via:
    • POST /get_block_record_by_height

Coins

  • POST /get_coin_record_by_name - one coin record by coin name
  • POST /get_coin_records_by_hint - coin records by single hint
  • POST /get_coin_records_by_hints - coin records by multiple hints
  • POST /get_coin_records_by_names - coin records by multiple coin names
  • POST /get_coin_records_by_parent_ids - coin records by parent_ids
  • POST /get_coin_records_by_puzzle_hash - coin records by one puzzle_hash
  • POST /get_coin_records_by_puzzle_hashes - coin records by puzzle_hashes
  • POST /get_memos_by_coin_name - memos for coin name
  • POST /get_puzzle_and_solution - coin solution by coin_id and optional height
  • POST /get_puzzle_and_solution_with_conditions - coin solution + conditions
  • POST /push_tx - submit a spend_bundle to mempool/blockchain

Fees

  • POST /get_fee_estimate - fee estimation for spend_bundle (supports target_times, spend_count)

Full Node

  • POST /get_aggsig_additional_data - network AGG_SIG additional data
  • POST /get_network_info - network metadata (network_name, prefix, genesis challenge)
  • POST /get_blockchain_state - full node/blockchain summary state
  • POST /get_network_space - estimated network space between two block header hashes

Mempool

  • POST /get_all_mempool_items - all mempool items
  • POST /get_all_mempool_tx_ids - all mempool tx ids (spend bundle hashes)
  • POST /get_mempool_item_by_tx_id - one mempool item by tx_id
  • POST /get_mempool_items_by_coin_name - mempool items by coin_name

WebSocket

  • GET /ws - realtime stream for new transactions, mempool items, and offer files

Integration Cheat Sheet (Required Body Fields)

Use this as a quick "minimum payload" guide when wiring clients.

Blocks

Endpoint Required body fields
POST /get_additions_and_removals header_hash
POST /get_block header_hash
POST /get_block_count_metrics none ({})
POST /get_block_record header_hash
POST /get_block_record_by_height height
POST /get_block_records start, end
POST /get_block_spends header_hash
POST /get_block_spends_with_conditions header_hash
POST /get_blocks start, end
POST /get_unfinished_block_headers none ({})

Coins

Endpoint Required body fields
POST /get_coin_record_by_name name
POST /get_coin_records_by_hint hint
POST /get_coin_records_by_hints hints
POST /get_coin_records_by_names names
POST /get_coin_records_by_parent_ids parent_ids
POST /get_coin_records_by_puzzle_hash puzzle_hash
POST /get_coin_records_by_puzzle_hashes puzzle_hashes
POST /get_memos_by_coin_name name
POST /get_puzzle_and_solution coin_id
POST /get_puzzle_and_solution_with_conditions coin_id
POST /push_tx spend_bundle

Fees / Full Node / Mempool / WebSocket

Endpoint Required body fields
POST /get_fee_estimate spend_bundle
POST /get_aggsig_additional_data none ({})
POST /get_network_info none ({})
POST /get_blockchain_state none ({})
POST /get_network_space newer_block_header_hash, older_block_header_hash
POST /get_all_mempool_items none ({})
POST /get_all_mempool_tx_ids none ({})
POST /get_mempool_item_by_tx_id tx_id
POST /get_mempool_items_by_coin_name coin_name
GET /ws none (upgrade to WebSocket)

Common Pitfalls

  • Prefer explicit Content-Type: application/json on all POST calls.
  • Send {} for endpoints with empty request bodies instead of omitting the body.
  • Treat hash-like fields as hex strings exactly as documented (for example 0x... values).
  • push_tx appears in multiple docs paths, but the route is the same API call (POST /push_tx).
  • Coin query defaults may return only unspent records unless include_spent_coins is set.
  • Keep API host and docs host separate:
    • docs: https://www.coinset.org/docs
    • API: https://api.coinset.org

Known Runtime Quirks

  • Some runtime environments can get blocked by upstream protections when using generic/default HTTP clients. Using a stable, explicit User-Agent header improves reliability for scripted calls.
  • Expect mixed field typing in some responses (int/decimal-string/hex-string). Parse defensively in automation.
  • For long scans over many blocks, build fail-soft behavior so single malformed or transiently failing blocks do not abort the entire run.

Quick Request Patterns

curl -X POST "https://api.coinset.org/<endpoint>" \
  -H "Content-Type: application/json" \
  -d '<json body>'
wscat -c wss://coinset.org/ws

Notes

  • Some docs links point to additional pages not yet verified in this file (for example, several "Previous/Next" links outside this fetched set).
  • The docs mention a CLI utility on the intro page, but a dedicated setup guide was not discovered in the fetched pages.

Source Pages