Docs

Build on nodexch

Everything a first integration needs, in the order you meet it. Every route and its fields are in the API reference.

Quickstart

nodexch speaks the Coinset API: every method is POST /<method> on https://api.nodexch.com with a JSON body, and the node's answer comes back byte for byte. A Coinset client changes its base URL and adds a key.

Each example reads the gateway from NODEXCH_URL and your key from NODEXCH_KEY. They are run against a real gateway before every release, so they work as written.

examples/curl/first-call.sh
#!/bin/sh
# The health check needs no key; every Coinset method is POST /<method> with a JSON body.
set -eu
url="${NODEXCH_URL:-https://api.nodexch.com}"

curl -fsS "$url/health"
echo

curl -fsS "$url/get_blockchain_state" \
  -H "Authorization: Bearer $NODEXCH_KEY" \
  -d '{}'
echo

The TypeScript example uses the typed client generated from the API's OpenAPI document: every path and request body is checked by the compiler. /openapi.json is the same document for any other generator.

Integers beyond 253 (netspace, large amounts) arrive exactly as the node wrote them, which JSON.parse rounds silently, so parse such answers with a big-integer-aware parser where the exact value matters; event frames write them as strings.

What you can call

nodexch answers Coinset's methods and adds channels of its own under /x/…. These are the families, each with a few of its routes; all of them, with every field, are in the API reference.

Blocks
Blocks, block records, their spends and the coins they add and remove./get_block_record_by_height/get_blocks/get_block_spends/get_additions_and_removals
Coins
Coin records by name, puzzle hash, parent or hint; puzzles and solutions./get_coin_record_by_name/get_coin_records_by_puzzle_hash/get_coin_records_by_hint/get_puzzle_and_solution
Transactions
Transactions with Coinset's summary of what they did, and reorgs./get_transaction/get_transactions_by_p2/get_pending_transactions_by_p2/get_reorgs
Addresses, tokens and NFTs
What an address holds: XCH, CAT tokens, NFTs and singletons./get_xch_balance_by_p2/get_cat_balances_by_p2/get_nft_ids_by_p2/get_singleton_info
Mempool and fees
What waits in the mempool, what a spend costs now, and submitting one./get_all_mempool_items/get_mempool_item_by_tx_id/get_fee_estimate/push_tx
Offers
Offers by id, token, NFT or address, their status, and the trade history./get_offer/get_offers_by_cat_asset_id/push_offer/x/offers/v1/trades
nodexch's own channels
The network's nodes, the mempool and fees in bands, token names and icons, the XCH price./x/node/v1/network/x/node/v1/mempool/x/node/v1/fees/x/assets/v1/assets/x/price/v1/xch
Live events
The same chain as a stream: a WebSocket or server-sent events./ws/events

Keys

Send a key as Authorization: Bearer <key>. Without one, only the probes (/up, /ready, /health), the OpenAPI document (/openapi.json) and this site answer.

  • Secret keys (nxs_…) are for servers. Never put one in a web page, an app bundle or a URL.
  • Publishable keys (nxp_…) are for browsers. They work only from the origins they were issued for, get no more from one visitor's address than a visitor without a key would, and never open the operator routes.
  • Browsers cannot set headers on a WebSocket or an EventSource, so /ws and /events also take a publishable key as ?key=. A secret key in a URL is refused.
  • A leaked key is rotated: the new key works at once and the old one stops at once, so have the new key ready to deploy when you rotate.

Limits

A key's plan sets a rate per minute, an allowance per month and a number of open streams. Every keyed answer says where you stand:

HeaderMeaning
x-ratelimit-limit, x-ratelimit-remainingRequests this minute
x-quota-limit, x-quota-remainingRequests this month
retry-afterOn a 429 or 503: seconds until the next try can succeed
x-nodexch-tierWhere the answer came from: a cache tier (immutable, peak, state, mempool), none, index, passthrough or stream
ETagSend it back as If-None-Match for a 304 while nothing changed

Answers the chain has not moved on come from the cache, so polling is cheap; the live events below are cheaper still.

Plans and the allowance

How a plan is paid for, what it grants and what happens at its edges. The account page shows all of it for your account.

  • Each plan is sold monthly or yearly; the yearly price is twelve months less the saving the pricing page shows. Chia has no pull payment, so every period is an invoice you pay on the account page in XCH: Sage in one click, or a Chia vault by address, amount and memo. The renewal invoice is made 7 days before the period ends, and a mail reminds you if you gave an address.
  • Your allowance is one per account, shared by all its keys. It runs from the day you subscribed to the same day of the next month, also on a yearly plan (it is granted month by month). Unused requests do not carry over. The account page shows what is left and the day it starts again, in UTC.
  • At zero, requests answer 429 quota_exceeded with a retry-after header, x-quota-reset and resets_at in the body: the moment the allowance starts again. Every answer carries x-quota-limit, x-quota-remaining and x-quota-reset. There are no top-ups: an upgrade starts a new period today with a full allowance.
  • An upgrade is paid in full now and starts a new period that day; the rest of the old period is not credited. A downgrade and a cancel take effect at the end of the paid period. There is no refund: the period you paid for runs out.
  • If a renewal is not paid, 7 days of grace follow the end of the period. Then the account and its keys are on the free plan: never blocked, only at the free limits. A later payment starts a fresh period that day.
  • An e-mail address is optional, but a paid plan needs a confirmed one: renewal reminders and security notices go there. It is never a way to sign in. If you lose every passkey, a link mailed to it registers a new passkey that signs in 24 hours later; a passkey you still have can cancel it before. Without an address, a lost passkey cannot be recovered.

Errors

nodexch's own errors are JSON with an HTTP status and a stable code:

An error
{"success": false, "error": "an API key is required: send Authorization: Bearer <key>", "code": "unauthorized"}

A refusal from the node itself keeps Coinset's shape instead: HTTP 200 with success: false and error (a block that does not exist, for example). Check success on every answer.

StatusCodeWhen
400bad_request, validation_failedThe body is not JSON, or a field is missing or malformed; the error names the field.
401unauthorizedNo key, or one the gateway does not know or that was revoked.
401key_expiredThe key's plan ran past its paid-until date.
403forbiddenThe key may not use this route: a publishable key on an operator route, or from an origin it was not issued for.
404not_foundNo such route or method.
429rate_limited, quota_exceededPast the rate per minute or the monthly allowance; wait retry-after seconds.
501not_enabledThis deployment does not serve that family of methods ("index not enabled").
502upstream_failedThe node or the upstream failed to answer.
503unavailableStarting up or out of budget; retry-after says when to try again.

Paging

The Coinset methods page as Coinset does: height ranges with start and end (end not included, at most 1,000 blocks at once).

nodexch's own lists under /x/… take limit and cursor. Each page carries next_cursor; pass it as cursor for the next page, until it is null.

The trade history, page by page
curl -s "https://api.nodexch.com/x/offers/v1/trades?asset_id=xch&limit=100" \
  -H "Authorization: Bearer $NODEXCH_KEY"
curl -s "https://api.nodexch.com/x/offers/v1/trades?asset_id=xch&limit=100&cursor=<next_cursor>" \
  -H "Authorization: Bearer $NODEXCH_KEY"

Live events

One WebSocket, /ws?events=peak,transaction,reorg,dashboard, or the same frames as server-sent events on /events. Without events a stream gets Coinset's four types; offer is nodexch's own and comes only when asked for.

Every frame is {"network", "seq", "message": {"type", "data"}}. seq counts every frame the gateway sends, so a stream that asked for fewer types sees gaps; they are not lost frames.

examples/typescript/events.ts
// The live events: open /ws, wait for the next peak, close. Frames are
// {"network","seq","message":{"type","data"}}, as Coinset sends them.
import { eventsUrl } from "../../clients/typescript/src/index.ts";

const base = process.env.NODEXCH_URL ?? "https://api.nodexch.com";
// Browsers put a publishable key in the URL; a server may send its secret key as a header instead.
const socket = new WebSocket(eventsUrl(base, ["peak"], process.env.NODEXCH_PUBLISHABLE_KEY));

let done = false;
const timeout = setTimeout(() => {
  console.error("no peak within 60 s");
  process.exit(1);
}, 60_000);

socket.addEventListener("message", (event) => {
  const frame = JSON.parse(String(event.data));
  if (frame.message?.type === "peak") {
    console.log(`peak ${frame.message.data.height} on ${frame.network} (seq ${frame.seq})`);
    done = true;
    clearTimeout(timeout);
    socket.close();
  }
});
socket.addEventListener("error", () => {
  if (done) return;
  console.error("the stream failed");
  process.exit(1);
});
  • peak

    A new peak; tx says whether it is a transaction block.

    Example frame
    peak
    {
      "network": "mainnet",
      "seq": 1,
      "message": {
        "type": "peak",
        "data": {
          "height": 8412345,
          "header_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "tx": true,
          "timestamp": 1790480000
        }
      }
    }
  • transaction

    Mempool ids in batches: pending when they arrive, confirmed with the block that took them, removed when they left without one.

    Example frames (3)
    transaction · pending
    {
      "network": "mainnet",
      "seq": 2,
      "message": {
        "type": "transaction",
        "data": {
          "ids": [
            "0x7777777777777777777777777777777777777777777777777777777777777777"
          ],
          "status": "pending",
          "height": null
        }
      }
    }
    transaction · confirmed
    {
      "network": "mainnet",
      "seq": 3,
      "message": {
        "type": "transaction",
        "data": {
          "ids": [
            "0x7777777777777777777777777777777777777777777777777777777777777777"
          ],
          "status": "confirmed",
          "height": 8412346
        }
      }
    }
    transaction · removed
    {
      "network": "mainnet",
      "seq": 4,
      "message": {
        "type": "transaction",
        "data": {
          "ids": [
            "0x8888888888888888888888888888888888888888888888888888888888888888"
          ],
          "status": "removed",
          "height": null
        }
      }
    }
  • reorg

    The peak moved to another branch; anything read at the old heights may have changed.

    Example frame
    reorg
    {
      "network": "mainnet",
      "seq": 5,
      "message": {
        "type": "reorg",
        "data": {
          "old_peak_height": 8412346,
          "old_peak_hash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
          "new_peak_height": 8412346,
          "new_peak_hash": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
          "reorg_depth": 1,
          "detected_at_ms": 1790480031250
        }
      }
    }
  • dashboard

    The feed an explorer's front page needs, one kind at a time.

    Example frames (4)
    dashboard · mempool_delta
    {
      "network": "mainnet",
      "seq": 6,
      "message": {
        "type": "dashboard",
        "data": {
          "kind": "mempool_delta",
          "added": [
            {
              "id": "0x7777777777777777777777777777777777777777777777777777777777777777",
              "first_seen_ms": 1790480012000,
              "fee_mojos": 50000000,
              "cost": 12000000,
              "spends": 2,
              "additions": [
                {
                  "parent_coin_info": "0xdddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
                  "puzzle_hash": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
                  "amount": 1000
                }
              ],
              "removals": [
                {
                  "parent_coin_info": "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
                  "puzzle_hash": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
                  "amount": 1000
                }
              ],
              "addition_count": 3,
              "removal_count": 2,
              "kind": "cat",
              "asset_ids": [
                "0x9999999999999999999999999999999999999999999999999999999999999999"
              ],
              "assets": {
                "xch": "50000000",
                "cats": [
                  {
                    "asset_id": "0x9999999999999999999999999999999999999999999999999999999999999999",
                    "amount": "1000"
                  }
                ],
                "nfts": 0,
                "dids": 0,
                "singletons": 0
              }
            }
          ],
          "removed": [
            "0x8888888888888888888888888888888888888888888888888888888888888888"
          ]
        }
      }
    }
    dashboard · live
    {
      "network": "mainnet",
      "seq": 7,
      "message": {
        "type": "dashboard",
        "data": {
          "kind": "live",
          "peak_height": 8412345,
          "mempool_size": 236,
          "mempool_cost": 88500547228,
          "mempool_fees": 350012,
          "synced": true
        }
      }
    }
    dashboard · block
    {
      "network": "mainnet",
      "seq": 8,
      "message": {
        "type": "dashboard",
        "data": {
          "kind": "block",
          "height": 8412345,
          "header_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "timestamp": 1790480000,
          "fees": 350012,
          "additions": 42,
          "removals": 17,
          "record": {
            "height": 8412345,
            "header_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
            "timestamp": 1790480000,
            "fees": 350012,
            "weight": 36893488147419103000
          },
          "spends": 17,
          "assets": {
            "xch": "12209542198803",
            "cats": [
              {
                "asset_id": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
                "amount": "3938"
              }
            ],
            "nfts": 1,
            "dids": 0,
            "singletons": 2
          }
        }
      }
    }
    dashboard · netspace
    {
      "network": "mainnet",
      "seq": 10,
      "message": {
        "type": "dashboard",
        "data": {
          "kind": "netspace",
          "bytes": "16487192343748823040000",
          "difficulty": 2384,
          "height": 8412345
        }
      }
    }
  • offer

    A new offer from the Splash network, with Coinset's offer fields and the offer file to take it with (shortened here).

    Example frame
    offer
    {
      "network": "mainnet",
      "seq": 10,
      "message": {
        "type": "offer",
        "data": {
          "offer_id": "8b239d3813a72e10cec3efa6b05841017cef2828add97026cd8352a53378e4da",
          "status": "open",
          "first_seen_ms": 1790480012000,
          "last_updated_ms": 1790480012000,
          "maker_p2s": [
            "d8b1e0d9a0e46b3403dff2f6c27fc46bc13e6f5ee5ff09dc28d28d28d51be422"
          ],
          "offered_cat_asset_ids": [
            "ec25b77bc54df637392d6a0f542de65f45020405d0f36ced723bff2870c378b1"
          ],
          "requested_cat_asset_ids": [],
          "offered_nft_ids": [],
          "requested_nft_ids": [],
          "offered_xch_mojos": 0,
          "requested_xch_mojos": 500003000000,
          "offered_cat_mojos": {
            "ec25b77bc54df637392d6a0f542de65f45020405d0f36ced723bff2870c378b1": 1000
          },
          "fee_mojos": 0,
          "pending_p2s": [],
          "offer": "offer1qqr83wcuu2rykcmqvpsxygqqemhmlaekcenaz02ma6hs5w600dhjlv…",
          "source": "splash",
          "network": "mainnet"
        }
      }
    }

Agents (MCP)

AI agents read nodexch through its MCP server at https://api.nodexch.com/mcp: the offer book of a pair cheapest first, one offer with its text, decoding an offer, recent trades, the loan board and prices. It is read-only and never touches a wallet, and every tool call is charged in credits on your secret key, like the routes it uses.

Claude Code

Make a key for the agent on the Agents page, which fills it into this command, then add the server once. Claude Code keeps the key in its settings; in a project's .mcp.json write "NODEXCH_KEY": "${NODEXCH_KEY}" in the server's env to read it from the environment instead.

examples/mcp/claude-code.sh
#!/bin/sh
# Connects Claude Code to nodexch in one install (@nodexch/mcp, TASK-176.04): the offer book,
# offers, trades, the loan board and prices, publishing an offer, metered in credits on your secret
# API key (nodexch.com, Account); and the Xchonnect wallet tools, run on your computer, which ask
# your wallet to take, make or cancel offers (nodexch never sees those requests).
#
# --scope user: every project of yours; the key is stored in ~/.claude.json. In a project's
# .mcp.json write "NODEXCH_KEY": "${NODEXCH_KEY}" in its env instead: Claude Code reads it from
# the environment, and the key stays out of the file.
# The key is passed to `claude mcp add` as an argument (-e), visible in the process list while it runs.
set -eu
: "${NODEXCH_KEY:?set NODEXCH_KEY=nxs_...}"
url="${NODEXCH_URL:-https://api.nodexch.com}"
command -v npx >/dev/null 2>&1 || { echo "nodexch: Node.js 22.12 or newer is needed (npx runs @nodexch/mcp)" >&2; exit 1; }

claude mcp add --scope user nodexch -e NODEXCH_KEY="$NODEXCH_KEY" -e NODEXCH_URL="$url" \
  -- npx -y @nodexch/mcp
claude mcp list

The same install brings the Xchonnect wallet tools (@nodexch/mcp runs them on your computer): the agent pairs with your wallet and asks it to take or make offers, and the wallet decides within the rules you set for the agent. Trades never pass through nodexch.

Claude on the web, the desktop and the phone

Add https://api.nodexch.com/mcp as a custom connector; Claude signs in through nodexch with your passkey and gets a key of its own, so there is nothing to copy. Claude Free allows one custom connector, which leaves no room for the wallet plugin: the Agents page, Claude tab, says what that means and how to trade anyway.

In the browser, without a plugin

The Agents page pairs with your wallet itself, for an agent that works in your browser such as Claude in Chrome. The session stays in that browser, encrypted; nodexch signs each pairing for your account and cannot read the session; its relay carries only sealed messages. The agent and its provider see the page. From there it reads your wallet's rules, takes and makes offers, posts ladders and cancels; it is slower than a local plugin, and not yet tried with Claude in Chrome.

Claude Desktop, Cursor and VS Code

The same install in a config file. Put your key in place of nxs_your_secret_key (VS Code asks for it), or take the file from the Agents page, which fills it in; where each file lives is said there.

examples/mcp/claude-desktop.json
{
  "mcpServers": {
    "nodexch": {
      "command": "npx",
      "args": ["-y", "@nodexch/mcp"],
      "env": {
        "NODEXCH_KEY": "nxs_your_secret_key"
      }
    }
  }
}

Tools

What each tool does and what one call costs at most: the weights of the routes it runs, a quarter for a cached answer, nothing for a failure. Each result says what it cost and what is left.

ToolCreditsWhat it does
search_assets1Finds a token's asset id by ticker or name.
offer_book2The open offers of a pair, cheapest first.
best_offer3The cheapest offer of a pair, with its text to take it.
get_offer1One open offer: amounts, price, expiry and its text.
partial_offers2Partial offers
get_partial_offer1Get a partial offer
decode_offer2Reads an offer text: what it gives, asks for and costs.
post_offer5Publishes an offer your wallet made to the book and the Splash network.
recent_trades1Taken offers, newest first.
loan_board1Open loan offers on this network.
prices2XCH in USD and token prices in XCH.

The protocol messages themselves (initialize, tools/list) cost nothing. A plan without a channel gets a tool error that names a plan with it.

By hand

examples/curl/mcp.sh
#!/bin/sh
# The MCP server for agents is POST /mcp with a secret key: one JSON-RPC message per request.
# An MCP client (Claude Code) does this for you; here is what it sends.
set -eu
: "${NODEXCH_KEY:?set NODEXCH_KEY=nxs_...}"
url="${NODEXCH_URL:-https://api.nodexch.com}"

mcp() {
  curl -fsS "$url/mcp" \
    -H "Authorization: Bearer $NODEXCH_KEY" \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' \
    -d "$1"
  echo
}

mcp '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
mcp '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'