SearchPay

SearchPay is a pay-per-query search API for agents built on the official Stellar x402 stack. It turns Brave Search into a paid Stellar USDC resource with a focused API, a TypeScript SDK, and a live dashboard.

Live Deployment

• API app: https://fly.io/apps/searchpay-api
• API base URL: https://searchpay-api.fly.dev
• Dashboard: https://search-pay.vercel.app/

What SearchPay Provides

• paid Brave-powered search endpoint protected by x402
• TypeScript SDK for agent-side paid requests
• live dashboard with SSE event streaming
• telemetry and rate-limiting on protected routes
• end-to-end demo flow for funded Stellar testnet accounts

Official x402 + Stellar Stack

SearchPay is aligned with the official Stellar x402 packages:

• @x402/core
• @x402/express
• @x402/fetch
• @x402/stellar

The API protects /search with official middleware and delegates verify/settle to the x402 facilitator at https://www.x402.org/facilitator (optionally with X402_FACILITATOR_API_KEY).

Architecture

Agent SDK / demo
        |
        |  x402 client + Stellar signer
        v
SearchPay API (Express)
  - official @x402/express middleware
  - official @x402/stellar exact server scheme
  - Brave Search proxy
  - SSE event stream
        |
        |  verify + settle
        v
x402 Facilitator
  - official Stellar x402 settlement flow
        |
        v
Stellar network

Repo Layout

SearchPay/
├── demo/                     # end-to-end runner
├── docs/                     # architecture, API, deployment, and ops docs
├── packages/
│   ├── server/               # SearchPay API on official x402 middleware
│   ├── sdk/                  # agent SDK wrapper on official x402 fetch client
│   └── dashboard/            # Next.js live dashboard
├── soroban-contract/         # optional app-specific contract experiments
├── Dockerfile                # multi-target api/web/demo build
├── docker-compose.yml        # local stack orchestration
└── .github/workflows/ci.yml  # CI

Prerequisites

• Node.js 22+
• pnpm
• Rust toolchain for soroban-contract/ tests
• funded Stellar testnet agent account with XLM and testnet USDC
• funded Stellar testnet payout account with a USDC trustline
• Brave Search API key

Environment

Create a root .env from the example:

cp .env.example .env

Key values:

BRAVE_API_KEY=BSA...
RESOURCE_SERVER_STELLAR_ADDRESS=G...
AGENT_STELLAR_SECRET=S...
FACILITATOR_URL=http://localhost:3001
X402_FACILITATOR_URL=https://www.x402.org/facilitator
STELLAR_NETWORK=testnet
STELLAR_RPC_URL=https://soroban-testnet.stellar.org
QUERY_PRICE_USDC=0.001
NEXT_PUBLIC_DASHBOARD_URL=http://localhost:3000

Notes:

• RESOURCE_SERVER_STELLAR_ADDRESS is the wallet that receives USDC for SearchPay queries.
• FACILITATOR_URL is the local SearchPay API URL used by the SDK and demo.
• NEXT_PUBLIC_DASHBOARD_URL is the dashboard URL used by the demo runner for hosted deployments.
• X402_FACILITATOR_URL is the upstream x402 settlement facilitator.
• X402_FACILITATOR_API_KEY is optional.

Local Commands

Three independent run commands:

pnpm api
pnpm web
pnpm demo

Convenience command:

pnpm dev

What they do:

• pnpm api: starts the SearchPay API on http://localhost:3001
• pnpm web: starts the dashboard on http://localhost:3000, or the next free port if 3000 is already in use
• pnpm demo: runs the funded-account end-to-end flow
• pnpm dev: runs the workspace dev servers together

Demo Flow

pnpm demo exercises the official x402 flow:

1. call /search without payment
2. receive 402 Payment Required
3. create x402 Stellar payment authorization with @x402/stellar
4. retry with official x402 payment headers
5. let the facilitator settle on Stellar
6. receive Brave search results
7. retry the same payment proof to confirm duplicate-proof rejection

The demo auto-starts the API and dashboard for localhost URLs when needed.

Verification

Install and verify:

pnpm install
pnpm typecheck
pnpm test
pnpm build
cargo test --manifest-path soroban-contract/Cargo.toml

Manual checks:

pnpm api
curl http://localhost:3001/health

pnpm web
open http://localhost:3000

pnpm demo

Docker

Build and run the local stack:

docker compose up --build

Services:

• api -> http://localhost:3001
• web -> http://localhost:3000

Optional demo container:

docker compose --profile demo up --build demo

CI

CI runs in GitHub Actions and covers:

• pnpm typecheck
• pnpm test
• pnpm build
• cargo test

Workflow file:

• .github/workflows/ci.yml

Contributing

Contributions are welcome.

Before opening a PR:

pnpm install
pnpm typecheck
pnpm test
pnpm build

If your change touches the funded payment flow, also run:

pnpm demo

Guidelines:

• keep changes aligned with the official Stellar x402 stack
• prefer extending the product layer over reintroducing custom payment protocol logic
• keep docs and env examples in sync with code
• avoid committing secrets or funded account material

Docs

• Docs Index
• Architecture
• API
• Deployment
• Operations
• Security

Current Maturity Notes

• event history is currently in-memory (no persistent database)
• Brave Search is the only upstream search provider today

License

SearchPay is released under the MIT License.