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.

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

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 /ws y /events tambié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:

CabeceraSignificado
x-ratelimit-limit, x-ratelimit-remainingPeticiones de este minuto
x-quota-limit, x-quota-remainingPeticiones de este mes
retry-afterCon un 429 o un 503: segundos hasta que el siguiente intento pueda salir bien
x-nodexch-tierDe dónde vino la respuesta: un nivel de caché (immutable, peak, state, mempool), none, index, passthrough o stream
ETagDevué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:

Un error
{"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.

EstadoCódigoCuándo
400bad_request, validation_failedEl cuerpo no es JSON, o falta un campo o está mal formado; el error nombra el campo.
401unauthorizedSin clave, o con una que el gateway no conoce o que fue revocada.
401key_expiredEl plan de la clave superó su fecha de pago.
403forbiddenLa clave no puede usar esta ruta: una clave publicable en una ruta del operador, o desde un origen para el que no se emitió.
404not_foundNo existe esa ruta o método.
429rate_limited, quota_exceededPor encima de la tasa por minuto o de la cuota mensual; espera retry-after segundos.
501not_enabledEste despliegue no sirve esa familia de métodos («index not enabled»).
502upstream_failedEl nodo o el upstream no respondió.
503unavailableArrancando 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.

El historial de operaciones, página a página
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.

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

    Un pico nuevo; tx dice si es un bloque de transacciones.

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

    IDs del mempool en lotes: pending al llegar, confirmed con el bloque que las incluyó, removed cuando salieron sin él.

    Frames de ejemplo (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

    El pico pasó a otra rama; cualquier cosa leída en las alturas anteriores puede haber cambiado.

    Frame de ejemplo
    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

    El feed que necesita la portada de un explorador, un kind cada vez.

    Frames de ejemplo (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

    Una 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
    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"
        }
      }
    }

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.

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

La 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.

examples/mcp/claude-desktop.json
{
  "mcpServers": {
    "nodexch": {
      "command": "npx",
      "args": ["-y", "@nodexch/mcp"],
      "env": {
        "NODEXCH_KEY": "nxs_your_secret_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.

HerramientaCréditosQué hace
search_assets1Busca el id de un token por su ticker o nombre.
offer_book2Las ofertas abiertas de un par, la más barata primero.
best_offer3La oferta más barata de un par, con su texto para aceptarla.
get_offer1Una oferta abierta: importes, precio, vencimiento y su texto.
partial_offers2Partial offers
get_partial_offer1Get a partial offer
decode_offer2Lee el texto de una oferta: qué da, qué pide y cuánto cuesta.
post_offer5Publica una oferta que hizo tu billetera en el libro y en la red Splash.
recent_trades1Ofertas aceptadas, las más recientes primero.
loan_board1Ofertas de préstamo abiertas en esta red.
prices2XCH 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

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"}'