Veridex Stellar x402

Veridex is a Stellar x402 v2 facilitator plus an HTTPS API gateway, Bazaar discovery, a keyless MCP agent interface, focused buyer/seller tooling, and an experimental provider-quality layer.

Payment authority, discovery recommendation, and provider-quality evidence are separate. Bazaar helps find resources; it cannot change a signed recipient, asset, network, or amount. Provider quality is a policy signal, not payment authorization.

Current status

Current validation scope is stellar:testnet. No pubnet/mainnet transaction or production-readiness claim is part of the current evidence set.

See the testnet acceptance matrix and conformance report for recorded transactions and limitations.

Related MCP server: x402 Stellar MCP Server

Testnet quickstart

Requirements: Node.js 22+ and Docker.

npm run demo

From a clean clone, this installs dependencies, creates fresh Friendbot-funded testnet accounts, writes .env, starts PostgreSQL/Bazaar/facilitator/reference seller, runs conformance, and writes conformance-report.json. The harness re-reads settlement from Stellar instead of trusting a returned hash.

For individual commands, expected output, clean-state steps, and port overrides, use the canonical testnet quickstart.

x402 v2 HTTP flow

buyer -> protected resource
resource -> HTTP 402 + PAYMENT-REQUIRED
buyer -> PAYMENT-SIGNATURE with a signed PaymentPayload
resource -> facilitator /verify
resource -> execute work
resource -> facilitator /settle
facilitator -> Stellar settlement
resource -> paid response + PAYMENT-RESPONSE

x402 v2 separates core types, scheme logic, and transport encoding:

• PaymentRequired contains x402Version, resource information, accepted PaymentRequirements, and optional extensions.

• PaymentRequirements contains scheme, CAIP-2 network, asset, atomic-unit amount, payTo, timeout, and scheme-specific extra.

• PaymentPayload contains the selected requirements in accepted plus the scheme-specific signed payload.

• SettleResponse reports success/failure, transaction, network, optional actual amount, and extensions.

• HTTP carries base64 JSON in PAYMENT-REQUIRED, PAYMENT-SIGNATURE, and PAYMENT-RESPONSE. X-PAYMENT and maxAmountRequired are v1 compatibility terminology, not active examples here.

The seller/resource server owns the HTTP 402 exchange. Veridex supplies the facilitator and optional discovery/evidence services; those are not additional sources of payment authority.

Buyer

import { createVeridexClient } from "@veridex/stellar";

const client = createVeridexClient({
  network: "stellar:testnet",
  privateKey: process.env.BUYER_SECRET_KEY!,
});

const response = await client.fetch("http://localhost:3003/paid-resource");
console.log(await response.json());

exact is the default. Use scheme: "upto" only for a route advertising the Veridex custom testnet scheme. The focused package is currently consumed from this repository or a packed tarball; do not assume registry publication. See the buyer guide.

Seller

The reference seller uses official @x402/hono and @x402/stellar server integration. It declares Bazaar metadata in PaymentRequired.extensions.bazaar through declareDiscoveryExtension(). After confirmed settlement, the facilitator queues catalog work to a durable local outbox and delivers it asynchronously to Bazaar.

Accepting payment does not require Bazaar, federation, or provider quality. See the seller guide.

Gateway seller

For an existing API, the gateway owns the 402/verify/settle edge and forwards the original request only after confirmed settlement:

existing HTTPS API -> gateway -> 402 -> facilitator -> Stellar -> original API

It preserves safe request fields, blocks private/reserved upstreams, applies timeouts/body/concurrency/rate limits, declares the same Bazaar extension, and records normalized payment/provider events for the future Developer Portal. Start with the gateway quickstart.

Bazaar and MCP

Veridex exposes:

• GET /discovery/resources for filtered catalog browsing.

• GET /discovery/search for PostgreSQL full-text plus lexical feature-hash/RRF search, opaque cursors, and bounded telemetry scores.

Feature hashing is lexical, not learned semantic retrieval. Current response shapes are in the Bazaar guide and OpenAPI.

The custom stdio MCP service exposes discover_resources and pay_resource. pay_resource is two-phase and exact-only: MCP returns a bounded challenge, the client wallet signs it, and MCP re-fetches/matches the challenge before submission. MCP does not hold a payer private key. See the MCP guide.

Veridex Stellar upto

upto separates the authorized maximum from the actual settled amount:

0 <= actual <= maximum

The payer signs bound terms including payer, payTo, token, ceiling, validity, facilitator, settlement ID, and request digest. After work executes, the facilitator attests to actual and the result digest. The active Soroban contract atomically pulls the ceiling, pays actual, refunds the remainder, leaves no residual allowance/balance, and records replay state.

Zero, partial, and full-cap usage are distinct outcomes. Zero is a terminal on-chain settlement that refunds the full ceiling; the ceiling is never an automatic charge. Over-cap settlement is rejected.

This is a Veridex testnet implementation. Installed stock @x402/stellar@2.21.0 exposes exact only, so upstream Stellar upto interoperability is not claimed. See the Stellar upto specification.

Documentation

• Quickstart

• Gateway, gateway quickstart, and Developer Portal boundary

• Developer guide index

• Buyer, seller, agent, and operator guides

• Architecture 3.2

• Standards alignment and drift policy

• Errors and payment proof

• Provider quality and federation

• Package selection

• Facilitator OpenAPI and Bazaar OpenAPI

Validate

npm run docs:check
npm run typecheck
npm test
npm run build
cargo test --locked --manifest-path contracts/upto-settlement/Cargo.toml

The repository is Apache-2.0. Optional Playground sharp/libvips artifacts have explicit license-policy exceptions and still require distribution review.