Documentación
Construye sobre nodexch
Todo lo que necesita una primera integración, en el orden en que lo encuentras. Cada ruta y sus campos están en la referencia de la API.
Inicio rápido
nodexch habla la API de Coinset: cada método es POST /<method> sobre https://api.nodexch.com con un cuerpo JSON, y la respuesta del nodo vuelve byte a byte. Un cliente de Coinset cambia su URL base y añade una clave.
Cada ejemplo lee el gateway de NODEXCH_URL y tu clave de NODEXCH_KEY. Se ejecutan contra un gateway real antes de cada versión, así que funcionan tal como están escritos.
#!/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 chain's peak through the typed client: every path and body is checked by TypeScript.
import { createNodexch } from "../../clients/typescript/src/index.ts";
const nodexch = createNodexch({
baseUrl: process.env.NODEXCH_URL ?? "https://api.nodexch.com",
key: process.env.NODEXCH_KEY,
});
const { data, error, response } = await nodexch.POST("/get_blockchain_state", { body: {} });
if (error || !data || data.success !== true) {
throw new Error(`get_blockchain_state answered ${response.status}: ${JSON.stringify(error ?? data)}`);
}
// The node's fields, described in the API reference; the spec types them as open objects.
const state = data.blockchain_state as { peak: { height: number }; sync: { synced: boolean } };
console.log(`peak ${state.peak.height}, synced: ${state.sync.synced}`);//! The chain's peak with reqwest: every Coinset method is `POST /<method>` with a JSON body.
//! (`cargo run --example first_call` from gateway/; in your own crate: reqwest with the `json`
//! feature, tokio and serde_json.)
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let url = std::env::var("NODEXCH_URL").unwrap_or_else(|_| "https://api.nodexch.com".into());
let key = std::env::var("NODEXCH_KEY")?;
let state: serde_json::Value = reqwest::Client::new()
.post(format!("{url}/get_blockchain_state"))
.bearer_auth(key)
.json(&serde_json::json!({}))
.send()
.await?
.error_for_status()?
.json()
.await?;
if state["success"] != true {
return Err(format!("the gateway said: {}", state["error"]).into());
}
let peak = &state["blockchain_state"]["peak"]["height"];
let synced = &state["blockchain_state"]["sync"]["synced"];
println!("peak {peak}, synced: {synced}");
Ok(())
}El ejemplo de TypeScript usa el cliente tipado generado a partir del documento OpenAPI de la API: el compilador comprueba cada ruta y cada cuerpo de petición. /openapi.json es el mismo documento para cualquier otro generador.
Los enteros por encima de 253 (netspace, cantidades grandes) llegan exactamente como los escribe el nodo, y JSON.parse los redondea sin avisar: analiza esas respuestas con un parser que entienda enteros grandes cuando importe el valor exacto; los frames de eventos los escriben como cadenas.
Qué puedes consultar
nodexch responde a los métodos de Coinset y añade canales propios bajo /x/…. Estas son las familias, cada una con algunas de sus rutas; todas, con cada campo, están en la referencia de la API.
- Bloques
- Bloques, registros de bloque, sus gastos y las monedas que añaden y eliminan.
/get_block_record_by_height/get_blocks/get_block_spends/get_additions_and_removals - Monedas
- Registros de moneda por nombre, puzzle hash, padre o hint; puzzles y soluciones.
/get_coin_record_by_name/get_coin_records_by_puzzle_hash/get_coin_records_by_hint/get_puzzle_and_solution - Transacciones
- Transacciones con el resumen de Coinset de lo que hicieron, y reorganizaciones.
/get_transaction/get_transactions_by_p2/get_pending_transactions_by_p2/get_reorgs - Direcciones, tokens y NFT
- Lo que tiene una dirección: XCH, tokens CAT, NFT y singletons.
/get_xch_balance_by_p2/get_cat_balances_by_p2/get_nft_ids_by_p2/get_singleton_info - Mempool y comisiones
- Lo que espera en la mempool, lo que cuesta un gasto ahora, y cómo enviarlo.
/get_all_mempool_items/get_mempool_item_by_tx_id/get_fee_estimate/push_tx - Ofertas
- Ofertas por id, token, NFT o dirección, su estado y el historial de operaciones.
/get_offer/get_offers_by_cat_asset_id/push_offer/x/offers/v1/trades - Los canales propios de nodexch
- Los nodos de la red, la mempool y las comisiones por tramos, nombres e iconos de tokens, el precio de XCH.
/x/node/v1/network/x/node/v1/mempool/x/node/v1/fees/x/assets/v1/assets/x/price/v1/xch - Eventos en vivo
- La misma cadena como flujo: un WebSocket o server-sent events.
/ws/events
Claves
Envía una clave como Authorization: Bearer <key>. Sin ella solo responden las sondas (/up, /ready, /health), el documento OpenAPI (/openapi.json) y este sitio.
- Las claves secretas (
nxs_…) son para servidores. Nunca pongas una en una página web, en el paquete de una app o en una URL. - Las claves publicables (
nxp_…) son para navegadores. Solo funcionan desde los orígenes para los que se emitieron, no obtienen de la dirección de un visitante más que un visitante sin clave y nunca abren las rutas del operador. - Los navegadores no pueden poner cabeceras en un WebSocket ni en un
EventSource, así que/wsy/eventstambién aceptan una clave publicable como?key=. Una clave secreta en una URL se rechaza. - Una clave filtrada se rota: la nueva funciona al instante y la antigua deja de hacerlo al instante, así que ten la nueva lista para desplegar cuando rotes.
Límites
El plan de una clave fija una tasa por minuto, una cuota por mes y un número de streams abiertos. Cada respuesta con clave te dice dónde estás:
| Cabecera | Significado |
|---|---|
x-ratelimit-limit, x-ratelimit-remaining | Peticiones de este minuto |
x-quota-limit, x-quota-remaining | Peticiones de este mes |
retry-after | Con un 429 o un 503: segundos hasta que el siguiente intento pueda salir bien |
x-nodexch-tier | De dónde vino la respuesta: un nivel de caché (immutable, peak, state, mempool), none, index, passthrough o stream |
ETag | Devuélvelo como If-None-Match para recibir un 304 mientras nada cambie |
Las respuestas que la cadena no ha dejado atrás vienen de la caché, así que consultar a menudo sale barato; los eventos en vivo de abajo son más baratos aún.
Planes y cuota
Cómo se paga un plan, qué da y qué pasa en sus bordes. La página de la cuenta lo muestra todo para tu cuenta.
- Cada plan se vende por meses o por años; el precio anual son doce meses menos el ahorro que muestra la página de precios. Chia no tiene cobro automático, así que cada periodo es una factura que pagas en la página de la cuenta en XCH: con Sage en un clic, o con una bóveda Chia por dirección, importe y memo. La factura de renovación se hace 7 días antes de que acabe el periodo, y un correo te lo recuerda si diste una dirección.
- Tu cuota es una por cuenta, compartida por todas sus claves. Va del día en que te suscribiste al mismo día del mes siguiente, también en un plan anual (se concede mes a mes). Las peticiones sin usar no se acumulan. La página de la cuenta muestra lo que queda y el día en que vuelve a empezar, en UTC.
- A cero, las peticiones responden 429 quota_exceeded con un encabezado retry-after, x-quota-reset y resets_at en el cuerpo: el momento en que la cuota vuelve a empezar. Cada respuesta lleva x-quota-limit, x-quota-remaining y x-quota-reset. No hay recargas: una mejora empieza hoy un periodo nuevo con la cuota completa.
- Una mejora se paga entera ahora y empieza un periodo nuevo ese día; el resto del anterior no se abona. Una bajada de plan y una cancelación entran en vigor al final del periodo pagado. No hay reembolso: el periodo que pagaste se agota.
- Si una renovación no se paga, siguen 7 días de gracia tras el fin del periodo. Después la cuenta y sus claves pasan al plan gratuito: nunca bloqueadas, solo con los límites gratuitos. Un pago posterior empieza un periodo nuevo ese día.
- El correo es opcional, pero un plan de pago necesita uno confirmado: a él van los avisos de renovación y de seguridad. Nunca sirve para iniciar sesión. Si pierdes todas las passkeys, un enlace enviado a él registra una passkey nueva que inicia sesión 24 horas después; una passkey que aún tengas puede cancelarlo antes. Sin dirección, una passkey perdida no se puede recuperar.
Errores
Los errores propios de nodexch son JSON con un estado HTTP y un código estable:
{"success": false, "error": "an API key is required: send Authorization: Bearer <key>", "code": "unauthorized"}Un rechazo del propio nodo conserva en cambio la forma de Coinset: HTTP 200 con success: false y error (un bloque que no existe, por ejemplo). Comprueba success en cada respuesta.
| Estado | Código | Cuándo |
|---|---|---|
| 400 | bad_request, validation_failed | El cuerpo no es JSON, o falta un campo o está mal formado; el error nombra el campo. |
| 401 | unauthorized | Sin clave, o con una que el gateway no conoce o que fue revocada. |
| 401 | key_expired | El plan de la clave superó su fecha de pago. |
| 403 | forbidden | La clave no puede usar esta ruta: una clave publicable en una ruta del operador, o desde un origen para el que no se emitió. |
| 404 | not_found | No existe esa ruta o método. |
| 429 | rate_limited, quota_exceeded | Por encima de la tasa por minuto o de la cuota mensual; espera retry-after segundos. |
| 501 | not_enabled | Este despliegue no sirve esa familia de métodos («index not enabled»). |
| 502 | upstream_failed | El nodo o el upstream no respondió. |
| 503 | unavailable | Arrancando o sin presupuesto; retry-after dice cuándo volver a intentarlo. |
Paginación
Los métodos de Coinset paginan como Coinset: rangos de altura con start y end (end no incluido, como mucho 1.000 bloques a la vez).
Las listas propias de nodexch bajo /x/… aceptan limit y cursor. Cada página trae next_cursor; pásalo como cursor para la siguiente página, hasta que sea null.
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"Eventos en vivo
Un WebSocket, /ws?events=peak,transaction,reorg,dashboard, o los mismos frames como eventos enviados por el servidor en /events. Sin events un stream recibe los cuatro tipos de Coinset; offer es propio de nodexch y solo llega cuando se pide.
Cada frame es {"network", "seq", "message": {"type", "data"}}. seq cuenta cada frame que envía el gateway, así que un stream que pidió menos tipos ve huecos; no son frames perdidos.
// 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);
});peakUn pico nuevo;
txdice si es un bloque de transacciones.Frame de ejemplo
{ "network": "mainnet", "seq": 1, "message": { "type": "peak", "data": { "height": 8412345, "header_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "tx": true, "timestamp": 1790480000 } } }transactionIDs del mempool en lotes:
pendingal llegar,confirmedcon el bloque que las incluyó,removedcuando salieron sin él.Frames de ejemplo (3)
{ "network": "mainnet", "seq": 2, "message": { "type": "transaction", "data": { "ids": [ "0x7777777777777777777777777777777777777777777777777777777777777777" ], "status": "pending", "height": null } } }{ "network": "mainnet", "seq": 3, "message": { "type": "transaction", "data": { "ids": [ "0x7777777777777777777777777777777777777777777777777777777777777777" ], "status": "confirmed", "height": 8412346 } } }{ "network": "mainnet", "seq": 4, "message": { "type": "transaction", "data": { "ids": [ "0x8888888888888888888888888888888888888888888888888888888888888888" ], "status": "removed", "height": null } } }reorgEl pico pasó a otra rama; cualquier cosa leída en las alturas anteriores puede haber cambiado.
Frame de ejemplo
{ "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 } } }dashboardEl feed que necesita la portada de un explorador, un
kindcada vez.Frames de ejemplo (4)
{ "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" ] } } }{ "network": "mainnet", "seq": 7, "message": { "type": "dashboard", "data": { "kind": "live", "peak_height": 8412345, "mempool_size": 236, "mempool_cost": 88500547228, "mempool_fees": 350012, "synced": true } } }{ "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 } } } }{ "network": "mainnet", "seq": 10, "message": { "type": "dashboard", "data": { "kind": "netspace", "bytes": "16487192343748823040000", "difficulty": 2384, "height": 8412345 } } }offerUna oferta nueva de la red Splash, con los campos de oferta de Coinset y el archivo de oferta para aceptarla (abreviado aquí).
Frame de ejemplo
{ "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" } } }
Agentes (MCP)
Los agentes de IA leen nodexch a través de su servidor MCP en https://api.nodexch.com/mcp: el libro de ofertas de un par, la más barata primero, una oferta con su texto, la decodificación de una oferta, las operaciones recientes, el tablón de préstamos y los precios. Solo lee, nunca toca una wallet, y cada llamada a una herramienta se cobra en créditos en tu clave secreta, como las rutas que usa.
Claude Code
Crea una clave para el agente en la página de agentes, que la pone en este comando, y añade el servidor una vez. Claude Code guarda la clave en su configuración; en el .mcp.json de un proyecto escribe "NODEXCH_KEY": "${NODEXCH_KEY}" en el env del servidor para leerla del entorno.
#!/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 listLa misma instalación trae las herramientas de billetera de Xchonnect (@nodexch/mcp las ejecuta en tu ordenador): el agente se empareja con tu billetera y le pide aceptar o crear ofertas, y la billetera decide dentro de las reglas que fijas para el agente. Las operaciones nunca pasan por nodexch.
Claude en la web, el escritorio y el móvil
Añade https://api.nodexch.com/mcp como conector personalizado; Claude inicia sesión a través de nodexch con tu passkey y recibe una clave propia, así que no hay nada que copiar. Claude Free permite un conector personalizado, y no queda sitio para el plugin de la wallet: la página de agentes, pestaña Claude, explica qué significa y cómo operar de todos modos.
En el navegador, sin plugin
La página de agentes se empareja ella misma con tu billetera, para un agente que trabaja en tu navegador, como Claude in Chrome. La sesión se queda cifrada en ese navegador; nodexch firma cada emparejamiento para tu cuenta y no puede leer la sesión; su relay solo lleva mensajes sellados. El agente y su proveedor ven la página. Desde ahí lee las reglas de tu billetera, acepta y crea ofertas, publica escaleras y cancela; es más lento que un plugin local y aún no se ha probado con Claude in Chrome.
Claude Desktop, Cursor y VS Code
La misma instalación en un archivo de configuración. Pon tu clave en lugar de nxs_your_secret_key (VS Code la pide), o toma el archivo de la página de agentes, que la rellena; allí se indica dónde va cada archivo.
{
"mcpServers": {
"nodexch": {
"command": "npx",
"args": ["-y", "@nodexch/mcp"],
"env": {
"NODEXCH_KEY": "nxs_your_secret_key"
}
}
}
}{
"mcpServers": {
"nodexch": {
"command": "npx",
"args": ["-y", "@nodexch/mcp"],
"env": {
"NODEXCH_KEY": "nxs_your_secret_key"
}
}
}
}{
"inputs": [
{
"type": "promptString",
"id": "nodexch-key",
"description": "nodexch secret API key (nxs_…)",
"password": true
}
],
"servers": {
"nodexch": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@nodexch/mcp"],
"env": {
"NODEXCH_KEY": "${input:nodexch-key}"
}
}
}
}Herramientas
Qué hace cada herramienta y cuánto cuesta como mucho una llamada: los pesos de las rutas que ejecuta, una cuarta parte para una respuesta en caché, nada si falla. Cada resultado dice cuánto costó y cuánto queda.
| Herramienta | Créditos | Qué hace |
|---|---|---|
search_assets | 1 | Busca el id de un token por su ticker o nombre. |
offer_book | 2 | Las ofertas abiertas de un par, la más barata primero. |
best_offer | 3 | La oferta más barata de un par, con su texto para aceptarla. |
get_offer | 1 | Una oferta abierta: importes, precio, vencimiento y su texto. |
partial_offers | 2 | Partial offers |
get_partial_offer | 1 | Get a partial offer |
decode_offer | 2 | Lee el texto de una oferta: qué da, qué pide y cuánto cuesta. |
post_offer | 5 | Publica una oferta que hizo tu billetera en el libro y en la red Splash. |
recent_trades | 1 | Ofertas aceptadas, las más recientes primero. |
loan_board | 1 | Ofertas de préstamo abiertas en esta red. |
prices | 2 | XCH en USD y precios de tokens en XCH. |
Los mensajes del protocolo (initialize, tools/list) no cuestan nada. Un plan sin un canal recibe un error de herramienta que nombra un plan que lo incluye.
A mano
#!/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"}'