Stellar Bazaar

Stellar Bazaar is an open-source foundation for a Stellar x402 facilitator and discovery network. The project is intended to build on @x402/stellar and make it practical for sellers, buyers, agents, and infrastructure operators to discover paid HTTP resources and settle x402 payments on Stellar.

Vision

The long-term goal is to provide:

• a production-ready x402 facilitator for Stellar
• /verify, /settle, and /supported facilitator endpoints
• Bazaar discovery endpoints at /discovery/resources and /discovery/search
• automatic cataloging of x402 resources that publish Bazaar discovery metadata
• HTTP and MCP resource discovery
• an MCP server for agent search and paid calls
• Stellar testnet and pubnet support
• future support for the x402 upto payment scheme
• hosted and self-hosted deployment paths

Current Scope

The MVP integrates the official x402 v2 Stellar exact scheme and demonstrates the complete testnet path: discover a resource, receive HTTP 402, create a buyer authorization, verify it, settle it, and receive the protected result. The settlement is independently inspectable on Stellar testnet.

It currently provides:

• real /supported, /verify, and /settle facilitator endpoints
• a PostgreSQL-backed /discovery/resources endpoint with bounded filters and pagination
• one controlled paid testnet resource carrying official Bazaar discovery metadata
• an end-to-end demo using the official Stellar and x402 client packages
• shared configuration and types
• Bazaar resource types, repository/search interfaces, and PostgreSQL/in-memory repositories
• SDK package scaffolding for future seller and buyer helpers
• strict TypeScript, linting, formatting, tests, Docker, Compose, and CI

Automatic metadata ingestion, /discovery/search, MCP tools, pubnet, and the upto scheme are deliberately not claimed by this MVP.

Planned Architecture

apps/
  facilitator/   HTTP facilitator service for x402 over Stellar
  mcp/           future MCP discovery server for agents

packages/
  bazaar/        discovery metadata, catalog repository, and search interfaces
  sdk/           seller and buyer helper utilities
  shared/        shared configuration, HTTP helpers, and public types

Payment handling is delegated to @x402/stellar. Discovery remains separate from payment execution so cataloging, search, and agent workflows can evolve without acquiring payment authority.

Development

Requirements:

• Node.js 22 or newer
• npm 10 or newer

Install dependencies:

npm install

Run checks:

npm run format:check
npm run lint
npm run typecheck
npm test

Run a disposable-account Stellar testnet settlement demo:

npm run demo:testnet -w @stellar-bazaar/facilitator

The demo funds fresh buyer, facilitator, and seller accounts through Friendbot, starts the controlled resource, confirms its unpaid 402, and uses @x402/fetch to authorize and retry the request. The resource delegates verification and settlement to the local facilitator before returning its result. Testnet secret keys exist only in memory for that run.

See docs/testnet-evidence.md for the first confirmed transaction and reproduction details.

Start the facilitator locally:

cp .env.example .env
# Set FACILITATOR_PRIVATE_KEY to a funded Stellar testnet account secret.
# Set DEMO_SELLER_ADDRESS to expose and catalog the paid address inspector.
npm run dev -w @stellar-bazaar/facilitator

The service listens on http://localhost:4020 by default.

API Status

• GET /health returns service health and configured Stellar network.
• GET /supported reports x402 v2, exact, stellar:testnet, fee sponsorship, and the configured facilitator signing address.
• POST /verify validates the x402 v2 request envelope and delegates Stellar transaction verification and simulation to @x402/stellar. It never submits a transaction.
• POST /settle delegates verification, transaction reconstruction, fee sponsorship, submission, and confirmation polling to @x402/stellar.
• GET /discovery/resources returns an x402 v2 Bazaar listing with bounded filtering and pagination. PostgreSQL is used when DATABASE_URL is configured; local runs without it use an empty in-memory catalog.
• GET /demo/address-inspect?address=... is enabled only when DEMO_SELLER_ADDRESS is configured. It returns an official x402 402 challenge and releases its deterministic address inspection result only after successful settlement.

Unit tests assert HTTP delegation, configuration, payment gating, and discovery behavior. They are not presented as proof of on-chain settlement; the reproducible testnet transaction provides that evidence.

See the MVP submission guide for the demonstrated flow, acceptance criteria, and intentionally deferred work.

License

Apache-2.0. See LICENSE.