Inspiration

We wanted to bring HTTP 402 Payment Required into the Polkadot ecosystem in a native, Substrate-first way. Existing X402 tooling worked well for EVM chains, but not for chains built on FRAME or ink!. That gap became the inspiration:

create a fully-functional, cryptographically verifiable micropayment protocol for Substrate networks — no EVM required.

We were also motivated by real problems API builders face:

  • Monetizing APIs without friction
  • Pay-per-request economics for AI, data, scraping, and infra workloads
  • Enabling wallets and chains to interoperate with HTTP-based protocols

polkax402 is our attempt to make that real for Polkadot.


What it does

polkax402 provides a complete X402 payment stack for Substrate networks, including:

  • A TypeScript SDK for client & server payment flows
  • A custom Substrate chain (polkax402) with built-in payment authorization logic
  • An ink! HTTPUSD contract supporting transferWithAuthorization
  • A Facilitator service that executes signed payments on-chain
  • A payment-gated Express server with dynamic pricing
  • A block explorer API for inspecting blocks, accounts, and extrinsics

The result is a fully working pay-per-use API model:

  1. Request → server returns 402 Payment Required
  2. Client auto-signs the payment
  3. Facilitator validates & settles it on-chain
  4. Request is retried automatically and returns 200 OK

It's the first turnkey X402 implementation for Substrate assets.


How we built it

We built polkax402 as a multi-component system:

🔶 1. Custom Substrate Chain

A minimal FRAME runtime with:

  • custom pallets for signature verification
  • ink! smart contract support
  • RPC endpoints deployed on Akash
  • HTTPUSD asset plumbing

🔶 2. ink! Contract (HTTPUSD)

Implements:

  • transferWithAuthorization
  • sr25519 signature verification
  • nonce replay protection
  • validity windows
  • facilitator execution flow

🔶 3. TypeScript SDK

A full client library:

  • wraps fetch to auto-handle 402 flows
  • creates signed payment headers
  • supports Polkadot.js extension
  • supports multiple networks (Polkadot, Kusama, Westend, AssetHub, etc.)

🔶 4. Facilitator Service

A payment executor:

  • takes signed authorizations
  • submits transfers on-chain
  • validates timestamps, signatures, and amounts

🔶 5. X402-Protected Express Server

Provides:

  • dynamic pricing
  • OpenAPI documentation
  • endpoints protected by x402
  • Firecrawl integration powered by HTTPayer relay
  • LLM summarization pipeline

🔶 6. Explorer API

REST endpoints for:

  • blocks
  • extrinsics
  • accounts
  • search

All services run via Docker Compose.


Challenges we ran into

Testnet tokens were a constant hurdle — especially around:

  • selecting networks that fully support ink!
  • working around toolchains not built for non-EVM signature flows
  • avoiding chains where contracts are disabled or frozen
  • debugging sr25519 signature mismatch issues

We also had to design the payment flow without relying on EVM-specific semantics like permit(), forcing us to implement our own signature, payload, and nonce standards.


Accomplishments that we're proud of

  • First true X402 implementation on Polkadot
  • Working, signed, verifiable payment proofs for Substrate networks
  • A fully deployed Substrate chain on Akash
  • A cross-component system (SDK + chain + facilitator + server + explorer) running end-to-end
  • Zero-friction TypeScript APIs that feel like using any normal fetch()

polkax402 demonstrates that Substrate chains can participate in modern, protocol-level payment flows — without needing EVM.


What we learned

  • ink! smart contract tooling is powerful but requires careful network selection.
  • Substrate signatures (sr25519) behave differently than secp256k1 and must be encoded consistently across client, facilitator, and contract.
  • HTTP 402 becomes much more powerful when the payment proof is cryptographic instead of trust-based.
  • Most chains underestimate the demand for request-level micropayments — but it’s becoming essential for AI, compute, and data APIs.
  • Substrate’s flexibility made it surprisingly easy to build a chain purpose-built for a single protocol.

What's next for polkax402

  • Cross-chain X402 payments via a bridge wrapper contract (likely powered by hyperbridge)
  • Support for Asset Hub USDC and assets on Polkadot/Kusama
  • Native Wasmtime compute payments for future DePIN workloads
  • A Rust server SDK
  • A browser-first SDK with fallback signatures
  • Expanding the facilitator to support batching, refunds, and multi-resource pricing
  • Deploying a managed X402 gateway for developers who want instant plug-and-play monetized APIs

polkax402 is just the first building block — we want to make Polkadot the best ecosystem for decentralized pay-per-use infrastructure.

Built With

Share this project:

Updates