feat(examples): add Spraay gateway server — multi-chain DeFi primitives via x402

[plagtech]

Description

Supersedes #1761 (rebased cleanly on current main to resolve conflicts).

Adds a new server example at examples/typescript/servers/spraay-gateway/ demonstrating how to protect a production API with 76+ DeFi endpoints using x402 payment middleware.

Spraay is a multi-chain batch payment protocol and x402 gateway that exposes DeFi primitives (batch payments, payroll, token swaps, escrow, AI inference, robot hiring) across 13 blockchains. This example shows agents how to discover and pay for these primitives per-request via x402 — no accounts, no API keys, no subscriptions.

What's included

• Express server with @x402/express middleware protecting 5 representative endpoints + 1 free discovery route
• Proxy pattern — demonstrates forwarding paid requests to a live upstream API (gateway.spraay.app), a common pattern for wrapping existing services with x402
• Tiered pricing — different prices per endpoint category ($0.01 for basic transfers, $0.05 for payroll/RTP, $0.03 for AI inference)
• Discovery endpoint — /discover returns the full endpoint catalog, pricing, and supported chains

Why this example is useful

1. Real-world proxy pattern — Most x402 examples are self-contained. This shows how to wrap an existing live API with x402, which is what most teams will actually do in production.
2. Multi-category pricing — Demonstrates tiered pricing across different endpoint types, not just a single /weather endpoint.
3. 13-chain coverage — Agents can access Base, Ethereum, Solana, Bitcoin, Stacks, and 8 other chains through a single x402-protected API.

Ecosystem context

• Live gateway: gateway.spraay.app
• MCP server: @plagtech/spraay-x402-mcp on Smithery
• Already in x402 ecosystem: Listed on x402.org/ecosystem (PR site(ecosystem): add Spraay x402 Gateway to Services/Endpoints #1278 merged)

Tests

This is an example server addition — no existing tests are modified. The server runs standalone against the live Spraay gateway API. Tested locally with ts-node src/index.ts and verified all 5 paid endpoints return proper 402 responses.

Checklist

• I have formatted and linted my code
• All new and existing tests pass
• My commits are signed (required for merge) -- you may need to rebase if you initially pushed unsigned commits
• I added a changelog fragment for user-facing changes (docs-only changes can skip)

[vercel]

@plagtech is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

[phdargen]

Thanks for the proposal @plagtech but examples should remain neutral and not highlight specific projects, that’s what the ecosystem page is for

[plagtech]

Thanks for the feedback @phdargen — totally understand, that makes sense. Happy to rework the examples to be neutral/generic and resubmit.

Also, could you point me to the right place to submit for the ecosystem page? Would love to get Spraay listed there as an x402 gateway implementation.

[phdargen]

Please see here for the ecosystem submission: https://github.com/x402-foundation/x402/tree/main/typescript/site#adding-your-project-to-the-ecosystem

You can add the example to the website you link there, I don't think a generic example in the x402 repo would add much wrt the examples we already have

[plagtech]

Perfect, appreciate the link! I'll get Spraay submitted through the ecosystem page. Thanks for the guidance 🤝