Documentación

Construye, cobra,
escala con Local402.

Cobra en tu moneda y recibe USDC en Stellar, de personas o agentes de IA. Guías, paquetes, referencia y una demo en testnet.

Empezar Ver la referencia

Pruébalo

Tu primer 402 → 200, gratis y sin wallet.

Paquetes

Servidor, cliente y MCP en npm.

Visión general

¿Qué es Local402?

Local402 extiende x402 en Stellar. Pones el precio en tu moneda (24 monedas del oráculo Reflector, y la UF) y recibes USDC exacto. Quien paga, persona o agente, elige USDC, XLM o EURC; si no es USDC, el contrato FxPay hace el swap en Soroswap dentro de la misma transacción. Cada venta deja un recibo con el precio local, la tasa y su fuente.

Ventajas clave

Pagos nativos para agentesPrecio por solicitud sobre HTTP 402.
Precio en tu moneda24 monedas y la UF; recibes USDC en Stellar.
Seguro y verificableEl agente revisa la tasa antes de firmar; si el swap no alcanza, se revierte todo.

Siguiente: prueba en testnet, tu primer pago 402 → 200.

Cómo funciona

Cuatro pasos y ningún tipo de cambio a mano.

Todo ocurre dentro del flujo x402 estándar. Si algo no cuadra, la transacción entera se revierte.

Precio local

El vendedor fija "70 NGN" en su ruta.

Oráculo Reflector

Lo pasa a USDC con la tasa on-chain, a favor del vendedor.

Paga con lo que tengas

USDC directo, o XLM y EURC con swap en Soroswap.

Recibo

USDC exacto al vendedor; el sobrante vuelve al cliente.

Comparación

x402 hoy, y con Local402.

Hoy x402 solo cobra en dólares y en un único activo. Pero el comercio real factura en pesos, reales, rupias, nairas, euros o yenes.

	x402 en Stellar hoy	Con Local402
Precio	En dólares; `"70 NGN"` falla	MXN, EUR, INR, NGN, CLP… (24 monedas) y UF, vía oráculo on-chain
El cliente paga con	Solo el activo exacto (USDC)	USDC, XLM o EURC, con swap atómico
El vendedor recibe	USDC	USDC exacto, sin exposición a XLM
Si el swap no alcanza	—	Se revierte todo; el sobrante vuelve
Agentes de IA	Confían en el precio del vendedor	Verifican la tasa, con tope por pago y presupuesto
Contabilidad	Montos en USDC	Recibo con precio local, tasa y fuente; CSV

Pruébalo

Seis APIs, seis monedas. Un solo USDC al otro lado.

Elige una ruta y mira su 402, gratis y sin wallet. Los botones de pago pagan de verdad en testnet.

agente@local402

Cargando…

Calculadora

Pon tu precio. Nosotros hacemos el cambio.

Cualquier monto en USD, UF o 24 monedas, y lo que cuesta pagarlo con cada activo.

Precio del vendedor

Mainnet

Lo mismo, con dinero real.

Mismo código en Stellar mainnet: USDC y EURC de Circle, Soroswap y Reflector reales. A la derecha, el último pago real tal como lo escribe /receipts.csv.

receipts.csv · 000004 · 2026-10-07

monto_local, moneda
50 CLP

activo_pagado, monto_pagado
USDC 0.0512658

usdc_recibido

0.0512658

transaccion
c5977d…6bb350

Pagado

GET /indicadores · 50 CLP · mainnet

Paga 50 pesos reales desde tu wallet.

Con Freighter en Mainnet; basta con tener XLM. Tú firmas, el facilitador paga la red y el cliente rechaza cobros sobre 200 CLP.

¿Eres un agente? Lo mismo desde la terminal, con tu propia clave y un tope por pago.

tu-wallet@mainnet

# desde tu wallet: elige USDC, XLM o EURC # o como agente, con tu clave: $ STELLAR_SECRET=S… npx -y local402-client pay https://local402-mainnet.vercel.app/indicadores --with XLM --max "100 CLP"

Fecha	Precio	Vendedor recibe	Cliente pagó	Prima vs Reflector	Transacción

Guías

Despliega en producción.

En local, npm run demo no necesita nada: crea y fondea cuentas desechables de testnet y levanta todo en localhost:3001.

terminal

git clone https://github.com/DiegoPoveda01/local402 && cd local402
npm install
npm run demo          # cuentas de testnet desechables, todo en marcha
 
# o por partes, copiando antes cada .env.example:
npm run facilitator   # :4022  liquida exact y exact-fx, paga las comisiones
npm run api           # :3001  vendedor de demo y panel
npm run agent         #        un cliente que paga
npm run mcp           #        servidor MCP

Un despliegue que sirven varios procesos, o que mueve dinero real, necesita además estas variables. Cada .env.example lista el resto.

Variable	Dónde	Para qué
`LOCAL402_QUOTE_SECRET`	vendedor	Firma las cotizaciones. Mismo valor en cada instancia, de al menos 32 caracteres (`openssl rand -hex 32`). Desde la 1.0 el vendedor no arranca sin ella; `quoteSecret: false` la desactiva en un vendedor de una sola instancia.
`KV_REST_API_URL, KV_REST_API_TOKEN`	vendedor	Recibos, topes de la demo y el último valor de la UF. Sin ellas, cada instancia serverless guarda los suyos y se pierden con ella.
`SELF_URL`	vendedor	Dónde compra el agente de la demo.
`CORS_ORIGIN`	vendedor	Orígenes del panel que pueden pagar desde la wallet del visitante, separados por comas.
`PAY_TO_ALLOWLIST, MIN_AMOUNT`	facilitador	Cada liquidación gasta comisiones del facilitador. En `stellar:pubnet` valen por defecto `PAY_TO` y 100000 (0,01 USDC).
`FACILITATOR_PRIVATE_KEYS`	facilitador	Una clave por liquidación simultánea; cada instancia, las suyas.
`FX_CONTRACT`	ambos	Obligatoria en mainnet: el FxPay al que queda atada la autorización del pagador.

Paquetes

Cobra con local402-server.

Una línea por ruta sobre el middleware de x402. localRoute pone el precio en tu moneda y ofrece exact (USDC) y exact-fx (XLM o EURC) con la misma cotización, así que todos pagan el mismo USDC.

server.ts

// npm install local402-server @x402/express express
import express from "express";
import { paymentMiddleware } from "@x402/express";
import { localRoute, local402Server } from "local402-server";
 
const payTo = "G…";   // tu cuenta de Stellar (G…) o un contrato (C…)
const app = express();
app.use(paymentMiddleware({
  "GET /africa": localRoute("70 NGN", { payTo }),
  "GET /uf": localRoute("0.01 UF", { payTo }),
}, local402Server("https://local402.vercel.app/facilitator")));

Opción	Por defecto	Qué hace
`price`	—	Precio local, como `"50 CLP"` o `"0.01 UF"`. Se redondea hacia arriba: el vendedor nunca recibe menos.
`payTo`	—	Dirección de Stellar que recibe el USDC, G… o C…. Si le pasas una clave secreta, la rechaza sin mostrarla.
`network`	`stellar:testnet`	O `stellar:pubnet`.
`oracle`	Reflector + UF	Fuente de tasas para cotizar.
`quoteSecret`	`LOCAL402_QUOTE_SECRET`	Firma las cotizaciones; `false` lo desactiva en una sola instancia.

local402Server(facilitatorUrl, network) crea el servidor de recursos que liquida exact y exact-fx con un facilitador de Local402 y publica la ruta en el catálogo Bazaar. Para cobrar herramientas MCP, local402-server/mcp exporta localToolPayment.

Paquetes

Paga con local402-client.

Lee el 402, vuelve a cotizar con su propio oráculo y solo firma si el precio y el swap están dentro de tus límites.

agent.ts

import { Local402Client } from "local402-client";
 
const client = new Local402Client({
  secret: process.env.STELLAR_SECRET,
  payWith: "XLM",        // USDC, XLM o EURC
  maxPrice: "500 CLP",   // rechaza cualquier pago por encima
});
const price = await client.quote(url);   // sin pagar
const paid = await client.pay(url);      // transaction, explorerUrl, body…

Opción	Por defecto	Qué hace
`secret / signer`	—	Clave del pagador, o un firmante que no la expone (una wallet del navegador).
`payWith`	`USDC`	USDC usa `exact`; XLM y EURC usan `exact-fx` a través de FxPay.
`maxPrice`	—	Tope por pago, en cualquier moneda soportada.
`budget`	—	Un `SpendingBudget`, como `"5000 CLP"`, compartible entre clientes.
`maxOverchargeBps`	200 (2%)	Rechaza cotizaciones por encima de su propio oráculo.
`maxFxPremiumBps`	500 (5%)	Rechaza swaps que puedan gastar más que esto sobre el valor del oráculo.
`fxSlippageBps`	200 (2%)	Margen que autoriza el swap; lo que no se usa se devuelve.
`network`	`stellar:testnet`	En `stellar:pubnet`, XLM y EURC necesitan además `fxContract` (`FXPAY_MAINNET`).
`oracle / assetOracle`	Reflector + UF	Tasas con que revisa la cotización del vendedor y la del swap.

También como CLI, sin escribir código:

terminal

npx -y local402-client quote https://local402-mainnet.vercel.app/africa
STELLAR_SECRET=S… npx -y local402-client pay <url> --with XLM --max "100 NGN"

Paquetes

Conecta un agente.

local402-mcp le da a tu agente cuatro herramientas para descubrir, cotizar y pagar, con un tope por pago y un presupuesto por sesión.

terminal

claude mcp add local402 \
  -e STELLAR_PRIVATE_KEY=S… \
  -e "MAX_PRICE=500 CLP" -- npx -y local402-mcp

Herramienta	Qué hace
`local402_discover`	Busca servicios en el catálogo x402 Bazaar del facilitador.
`local402_quote`	Precio local y tasa, sin pagar.
`local402_pay`	Paga con USDC, XLM o EURC.
`local402_wallet`	Saldo y presupuesto restante.

Variable	Por defecto	Qué hace
`STELLAR_IDENTITY / STELLAR_PRIVATE_KEY`	—	Cuenta que paga: una identidad de stellar-cli (preferida) o una clave secreta.
`PAY_WITH`	USDC	Activo con que paga: USDC, XLM o EURC.
`MAX_PRICE`	500 CLP	Rechaza cualquier pago por encima de este precio local.
`BUDGET`	5000 CLP	Deja de pagar cuando la sesión gastó este total.
`NETWORK`	`stellar:testnet`	O `stellar:pubnet`.
`FACILITATOR_URL`	el de Local402	Facilitador cuyo catálogo lista local402_discover.
`FX_CONTRACT`	FxPay de Local402 en mainnet	Contrato FxPay en que confía para XLM y EURC.
`HORIZON_URL`	Horizon público	Para leer saldos.

Referencia

La cotización del 402.

El 402 ofrece dos opciones con la misma cotización, en extra.local402: exact (USDC, el esquema estándar de x402) y exact-fx (XLM o EURC, que FxPay cambia a USDC). Míralo sin instalar nada:

terminal

# el precio está en nairas; el requisito, en USDC
curl -si https://local402-mainnet.vercel.app/africa \
  | grep -i '^payment-required' | cut -d' ' -f2 | tr -d '\r' | base64 -d

Campo	Qué es
`currency, localAmount`	El precio tal como lo puso el vendedor.
`usdPerUnit`	Valor en USD de una unidad de la moneda.
`tokenAmount, tokenDecimals`	Lo que hay que pagar, en la unidad mínima del token. Redondeado hacia arriba.
`oracleSource, oracleTimestamp`	De dónde salió la tasa y cuándo.
`oracleValueDate`	Día al que corresponde el valor, cuando difiere del timestamp (la UF).
`expiresAt`	Segundos unix tras los cuales el vendedor ya no la respeta.
`signature`	HMAC del vendedor, cuando las cotizaciones van firmadas.

Referencia

El esquema exact-fx.

Un borrador de esquema x402: el pagador entrega otro activo y el vendedor recibe el monto exacto en USDC. Un cliente x402 estándar paga la opción exact del mismo 402. Especificación completa.

`extra`	Tipo	Qué es
`areFeesSponsored`	`true`	El facilitador paga las comisiones de red, como en `exact`.
`fxContract`	string	Dirección de FxPay. El cliente solo firma para un contrato en que ya confía; no la toma del servidor.
`sendAssets`	string[]	Contratos de token que el facilitador acepta como activo del pagador.

El pagador firma una sola autorización:

FxPay

FxPay.pay(from, send_asset, max_send, dest_asset, dest_amount, pay_to, deadline)
 
// max_send: FxPay.quote(...) más 2% de margen; lo que no se usa vuelve en la misma llamada
// si la ruta necesita más que max_send: ExcessiveInput, y no se mueve nada

Referencia

Cuando algo sale mal.

Cada caso falla antes de que se mueva dinero, o revierte la transacción entera.

Situación	Qué pasa
La tasa del oráculo tiene más de 15 minutos, viene del futuro o es cero	El servidor no cotiza. No hay requisito, así que nadie paga con un precio malo.
El vendedor cotiza más de 2% sobre el oráculo del pagador	Local402Client se niega antes de firmar.
El swap podría gastar más de 5% sobre el valor del oráculo	El cliente se niega antes de firmar (`maxFxPremiumBps`).
Los pools se movieron y la ruta necesita más que `max_send`	FxPay revierte con `ExcessiveInput`. No se mueve nada.
Ningún pool entrega el activo del vendedor	FxPay falla con `NoRoute`.
Monto, destinatario o activo distintos de los del 402	El facilitador lo rechaza: `wrong_amount`, `wrong_recipient`, `wrong_asset`.
El plazo vence mientras el pagador aprueba en la wallet	`deadline_expired`. El cliente ya deja 180 s para firmar.
Las tres fuentes de la UF están caídas	Se usa la última UF conocida hasta por tres días; después solo deja de cotizar la ruta en UF.

Recibos en vivo

Cada venta, lista para contabilidad.

Exportar CSV

Hora	Recurso	Precio	Tasa (USD)	Vendedor recibe	Cliente pagó	Transacción
Aún no hay pagos. Prueba uno arriba.

Referencia

Lo que no hace.

No corrige el oráculo. Vendedor y pagador leen el mismo feed de Reflector, así que Local402 atrapa a un vendedor que cotiza mal, no a un feed equivocado. Pasa tu propio oracle al cliente para una lectura independiente.
No cubre el tipo de cambio. El vendedor recibe USDC; pasarlo a su moneda sigue siendo cosa suya.
No busca en todos los mercados. FxPay enruta solo por Soroswap, por el pool directo o pasando por XLM.
No custodia fondos. FxPay no guarda saldo entre pagos y no tiene funciones de admin ni de actualización.
No está auditado. Tiene tests y pagos reales liquidados, pero ninguna auditoría externa. Por eso el facilitador de mainnet solo liquida para el vendedor de la demo y desde 0,01 USDC.
exact-fx aún no es parte de x402. Es un borrador.

Referencia

Todo se puede verificar.

El contrato FxPay de mainnet, CA6Z4E…UGHD, es byte a byte el artefacto de un release de GitHub compilado en CI. stellar.expert lo muestra verificado contra el commit 268f32c (tag v0.1.1) y Stellar Lab, como Verified Build. Compruébalo sin confiar en esta página:

terminal

curl -fsSL -O https://github.com/DiegoPoveda01/local402/releases/download/v0.1.1_contracts_fx-pay_cli27.0.0/fx-pay_v0.1.1.wasm
sha256sum fx-pay_v0.1.1.wasm
curl -s https://api.stellar.expert/explorer/public/contract/CA6Z4E55YN6LZEXBQPFCWUIMUJGAV42RLHYWWZ6SNIP4E73R2I2PUGHD | jq -r .wasm
# ambos imprimen 69a12d89059be04ac195f5acf40982d7e9ee93fd08f4df33626789d00ffccbd2

Tests. npm test corre 41 tests de TypeScript y cargo test, 11 del contrato.
Escaneo. kuyfi probó 37 vectores sobre los cinco puntos de entrada, sin hallazgos. Es un escaneo de superficie, no una auditoría.
Upstream. Un bug de comisiones en mainnet, reportado en x402#3491; el arreglo, x402#3503, está integrado.
npm. local402-server, local402-client, local402-mcp.
Código. github.com/DiegoPoveda01/local402

Pruébalo

Agentes

Referencia

Paquetes

¿Qué es Local402?

Cuatro pasos y ningún tipo de cambio a mano.

Precio local

Oráculo Reflector

Paga con lo que tengas

Recibo

x402 hoy, y con Local402.

Seis APIs, seis monedas. Un solo USDC al otro lado.

Pon tu precio. Nosotros hacemos el cambio.

Lo mismo, con dinero real.

Paga 50 pesos reales desde tu wallet.

Convierte tu monto y paga por tu resultado.

Despliega en producción.

Cobra con local402-server.

Paga con local402-client.

Conecta un agente.

La cotización del 402.

El esquema exact-fx.

Cuando algo sale mal.

Cada venta, lista para contabilidad.

Lo que no hace.

Todo se puede verificar.