x402-dart

This repository contains the Dart implementation of the x402 protocol, a machine-native payment standard designed for the modern web.

This library currently only supports V2 of the protocol. V1 was marked legacy and is unsupported.

x402 enables instant, automatic stablecoin payments directly over HTTP by reviving the HTTP 402 "Payment Required" status code. This implementation provides a suite of both client- and server-side libraries to integrate x402 payments into your Dart and Flutter applications.

Official Resources

• Protocol Homepage: x402.org
• Protocol Specification & Reference: github.com/coinbase/x402

Monorepo Structure

This project is organized as a monorepo managed with Melos. It consists of several packages:

Why use x402 Dart?

• Native Dart & Flutter: Built from the ground up for the Dart ecosystem.
• Multi-Chain: Seamlessly handle payments on both EVM and SVM networks.
• Automated Handshake: Use the X402Client to automatically parse requirements, negotiate signers, and retry requests.
• Type-Safe Models: Robust serialization and validation for all protocol data structures.

Getting Started

For most use cases, you only need to add the main x402 package to your project:

dependencies:
  x402: ^0.3.0

If you prefer using Dio, you can use the x402_dio package:

dependencies:
  x402: ^0.3.0     # For signers (EvmSigner, SvmSigner)
  x402_dio: ^0.3.0 # For X402Interceptor

On the server side, you can turn your shelf route into a paid one using the x402PaymentMiddleware:

dependencies:
  x402: ^0.3.0     # For facilitator clients and resource servers
  x402_shelf: ^0.1.0 # For x402PaymentMiddleware

Quick Example

import 'package:x402/x402.dart';

void main() async {
  final evmSigner = EvmSigner.fromPrivateKeyHex(chainId: 123, privateKeyHex: 'EVM_PRIVATE_KEY');
  final svmSigner = await SvmSigner.fromPrivateKeyHex(privateKeyHex: 'SVM_PRIVATE_KEY', cluster: SolanaCluster.devnet);

  final client = X402Client(
    signers: [
      evmSigner, // The first signer is checked first
      svmSigner
    ],
    onPaymentRequired: (req, resource, signer) async {
      // Optional: Ask for user confirmation or add condition
      return true;
    },
  );

  final response = await client.get(Uri.parse('https://api.example.com/premium'));
  if (response.statusCode == 200) {
    print('Success: ${response.body}');
    // HTTP 402 is automatically handled inside X402Client (payment + retry),
    // so it will never reach this point and does not need to be checked here.
  } else {
    print('Request failed (${response.statusCode}): ${response.body}');
  }
}

Detailed examples for both automated and manual flows can be found in the examples folder. End-to-end tests can be found in the e2e folder.

Development

This repo uses Melos for workspace management.

# Bootstrap the workspace
melos bootstrap

# Format all Dart files
melos format

# Analyze all packages
melos analyze

# Run unit tests
melos test

# Run e2e tests
melos e2e

License

This project is licensed under the Apache-2.0 License.