Neuronto Payments

npx add-mcp 'https://pay.neuronto.com/mcp'

Neuronto Payments: referência para desenvolvedores

URL base: https://pay.neuronto.com. OpenAPI 3.1 em /openapi.json. Guia para agentes em /llms.txt.

O que é isto

Um facilitador x402. O x402 revive o 402 Payment Required do HTTP: um servidor responde a uma requisição não paga com 402 e termos legíveis por máquina, o cliente assina um pagamento em stablecoin, e um facilitador verifica a assinatura e liquida a transferência on-chain. Esta origem é esse facilitador. Ela não detém fundos: uma liquidação move USDC do pagador para o endereço anunciado pelo comerciante em uma única transação assinada pelo pagador; o facilitador a transmite e paga o gás.

Endpoints

Método e caminho	O que faz
GET /health	Verificação de atividade. Responde 200 enquanto aceita tráfego.
GET /supported	Todas as redes (x402Version, scheme, network) ativas no momento, os endereços de signatários que pagam o gás, e fatos por rede (ativo, nome e versão EIP-712). Uma rede é retirada aqui primeiro quando não consegue liquidar.
GET /verify, GET /settle	Dicas autodescritivas que nomeiam o corpo esperado.
POST /verify	Verifica um pagamento assinado contra seus requisitos. Não move nada. Gratuito.
POST /settle	Liquida on-chain. Idempotente por corpo. Cabeçalho Idempotency-Key opcional.
GET /discovery/resources	Catálogo de recursos pagos por meio deste facilitador: termos, método e formatos de entrada e saída quando o comerciante os publicou (extensão bazaar). limit, offset, network.
GET /discovery/stats	Estatísticas de liquidação e catálogo.
GET /status.json	Disponibilidade observada a partir de contadores de sondagem (limite inferior de Wilson, omitido abaixo de cinco sondagens), estado da rede, estado da triagem de endereços e contagens de liquidação. /status é a mesma coisa como página.
GET /echo	Um comerciante ativo para testar um cliente: ele responde 402, e um pagamento é reembolsado integralmente na mesma requisição. /echo/status informa se está ativo.
POST /mcp	Servidor MCP para agentes: facilitator_status, settlement_price, find_paid_resource, integration_snippet. Sem chave. GET e DELETE respondem 405, nunca 404.
GET /integrate	O caminho mais curto do zero até uma rota paga, em quatro frameworks.
GET /pricing	O preço de uma liquidação, como JSON; /pricing.md como Markdown.
GET /.well-known/ard.json	Manifesto Agentic Resource Discovery para esta API.

Aceitar pagamentos

Aponte qualquer SDK de servidor x402 para este facilitador e anuncie uma carteira que você controla. A mesma coisa com todos os frameworks, e iniciadores executáveis, está em /integrate. Python (FastAPI):

from x402.http import FacilitatorConfig, HTTPFacilitatorClient, PaymentOption
from x402.http.middleware.fastapi import PaymentMiddlewareASGI
from x402.http.types import RouteConfig
from x402.mechanisms.evm.exact import ExactEvmServerScheme
from x402.server import x402ResourceServer

facilitator = HTTPFacilitatorClient(FacilitatorConfig(url="https://pay.neuronto.com"))
server = x402ResourceServer(facilitator).register("eip155:8453", ExactEvmServerScheme())
routes = {"GET /premium": RouteConfig(
    accepts=[PaymentOption(scheme="exact", price="$0.01", network="eip155:8453", pay_to="0xYourWallet")],
    description="One premium answer")}
app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)

TypeScript (Express): new HTTPFacilitatorClient({ url: "https://pay.neuronto.com" }) no lugar de qualquer outro facilitador. Nada mais nos SDKs muda. Base (eip155:8453) está ativa. Para testar primeiro na Base Sepolia (eip155:84532), onde liquidações são gratuitas e USDC vem de um faucet, verifique se /supported a lista: o objeto networks ali marca cada rede como available ou não.

Pagar por coisas

Qualquer cliente x402 funciona sem alterações: ele nunca fala com o facilitador, apenas com o servidor que respondeu 402. Testar um cliente contra um 402 ativo exige um comerciante, e esta origem executa um:

curl -i https://pay.neuronto.com/echo          # 402 with terms, then pay it with any x402 client

/echo cobra $0,001 na Base e envia de volta imediatamente na mesma requisição; o gás é nosso. Há um limite por endereço e por dia, e /echo/status informa se está ativo agora. Nada nele é especial para este facilitador: é um recurso x402 comum que por acaso reembolsa.

Formatos de requisição e resposta

POST /verify e POST /settle recebem:

{"x402Version": 2, "paymentPayload": {...}, "paymentRequirements": {...}}

paymentPayload é o payload assinado do cliente exatamente como enviado em PAYMENT-SIGNATURE (decodificado); paymentRequirements é a opção que o servidor anunciou e o cliente aceitou. Verify responde {"isValid": true, "payer": "0x..."} ou {"isValid": false, "invalidReason": "...", "invalidMessage": "..."}. Settle responde {"success": true, "transaction": "0x...", "network": "eip155:8453", "payer": "0x...", "amount": "10000"} ou {"success": false, "errorReason": "...", "errorMessage": "...", "transaction": "", "network": "...", "payer": "..."}. Ambos mantêm o formato x402 em todos os códigos de status, porque os SDKs x402 analisam o corpo independentemente.

Razões que o pagador pode tratar começam com invalid_ (assinatura errada, nonce usado, janela expirada, saldo insuficiente). Razões que são do facilitador (transaction_failed, service_unavailable) nunca cobram ninguém e chegam ao operador. Mais uma: sanctioned_address significa que o endereço pagador, recebedor ou comerciante aparece na lista pública de sanções contra a qual este facilitador faz triagem; é recusado antes de qualquer chamada on-chain, então nada é cobrado e nenhuma transação é criada. A lista e sua idade são publicadas em /status.

Semântica de liquidação

• Uma vez por corpo. O JSON canônico da requisição é a identidade da liquidação. O corpo idêntico é liquidado uma vez; reenviá-lo retorna o resultado registrado com Idempotency-Replayed: true.
• Idempotency-Key (opcional) vincula-se ao primeiro corpo com o qual é enviado; a mesma chave com um corpo diferente é recusada com 422.
• Pendente. Uma liquidação responde em cerca de 25 segundos ou retorna errorReason: "settlement_pending" com o hash da transação se foi transmitida. Ela continua em segundo plano. Reenvie o corpo idêntico para consultar; um resultado pendente nunca é armazenado em cache, um final é.
• Ordem. Liquidações em uma rede são processadas uma de cada vez, na ordem recebida.
• Simulação antes da transmissão. A transferência é simulada novamente imediatamente antes de ser enviada, então um pagador que esvaziou sua carteira após a verificação falha limpo e sem custo de gás.
• Servir após liquidar. Entregue o recurso pago após success: true, não após verify: a verificação prova que o pagamento pode liquidar, a liquidação prova que liquidou.

Erros

/verify e /settle mantêm o formato x402. Todo o resto, incluindo caminhos desconhecidos, responde com detalhes de problema RFC 9457:

{"type": "https://pay.neuronto.com/developers#not-found", "title": "Not Found", "status": 404, "detail": "No resource is served at GET /no-such-path."}

not-found: nenhuma rota naquele caminho; não há prefixo /v1/. bad-request: o corpo não é JSON; em /verify e /settle isso chega como invalid_payload. payload-too-large: corpos acima de 65536 bytes. too-many-requests: veja limites de taxa. unprocessable-content: um Idempotency-Key reutilizado com um corpo diferente. internal-server-error: tente novamente com backoff; a resposta não carrega detalhes internos por design.

Limites de taxa

Por endereço de cliente, três baldes, para que uma liquidação não possa esgotar as leituras dentro de cada chamada paga: settle 50/s (rajada 100), payments-read ({/verify, /supported, /health}) 30/s (rajada 60), discovery (todo o resto) 10/s (rajada 20). Uma recusa é um problema 429 com Retry-After; toda resposta nomeia seu balde em RateLimit-Policy.

Redes

Rede	CAIP-2	nome v1	Ativo	Testnet
Base Sepolia	eip155:84532	base-sepolia	USDC 0x036CbD53842c5426634e7929541eC2318f3dCF7e	sim
Base	eip155:8453	base	USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913	não

O domínio EIP-712 sobre o qual um pagador assina difere por rede: USDC na Base é USD Coin versão 2; USDC na Base Sepolia é USDC versão 2. /supported carrega ambos para que um servidor nunca precise lembrar.

Versionamento

Pelo campo x402Version no corpo: 2 usa redes CAIP-2 (eip155:8453), 1 usa nomes curtos (base). Ambos são servidos nos mesmos caminhos. Um tipo de pagamento é retirado ao desaparecer de /supported antes que os endpoints parem de aceitá-lo.