x402 Crystal Implementation

Core Crystal implementation of the x402 Payment Protocol. This package provides the foundational types, schemas, and utilities that power all x402 integrations in Crystal.

Installation

Add this to your application's shard.yml:

dependencies:
  x402:
    github: your-username/x402-crystal
    version: ~> 0.1.0

Overview

The x402 Crystal package provides the core building blocks for implementing the x402 Payment Protocol in Crystal. It's designed to be used by:

• Server applications requiring payment enforcement
• Client-side payment handlers
• Custom integrations

Usage

Basic Client Usage

require "x402"

# Create payment requirements
network = X402::Types::Shared::Network::Base
price = 10.5
payment_requirements = X402::Types::Verify::PaymentRequirements.new(
  "exact",
  network,
  price
)

# Create a signer
signer = X402::Types::Shared::EvmSigner.new

# Create payment header
payment_header = X402::Client.create_payment_header(
  signer,
  X402::X402_VERSION,
  payment_requirements
)

Server-Side Verification and Settlement

# Verify a payment
verification_result = X402::Facilitator.verify(
  client,
  payment_payload,
  payment_requirements
)

if verification_result.is_valid
  # Settle the payment
  settlement_result = X402::Facilitator.settle(
    signer,
    payment_payload,
    payment_requirements
  )
  
  if settlement_result.success
    # Process the user's request
    puts "Payment settled successfully: #{settlement_result.transaction}"
  end
end

Supported Networks

The implementation supports EVM, SVM, and TVM networks:

EVM Networks:

• Abstract
• Abstract Testnet
• Base
• Base Sepolia
• Avalanche
• Avalanche Fuji
• Iotex
• Sei
• Sei Testnet
• Polygon
• Polygon Amoy
• Peaq
• Story
• Educhain
• Skale Base Sepolia

SVM Networks:

• Solana
• Solana Devnet

TVM Networks:

• Everscale

Architecture

The implementation is organized into several key modules:

• X402::Types: Core type definitions
• X402::Client: Client-side payment creation
• X402::Facilitator: Server-side verification and settlement
• X402::Schemes: Payment scheme implementations
• X402::Utils: Utility functions

Payment Schemes

Currently, the implementation supports the "exact" payment scheme:

• Exact: Requires an exact payment amount to be made to a specified address

Future versions may support additional schemes like "minimum" or "range".

API Reference

Types

• X402::Types::Shared::Network: Enum for supported blockchain networks
• X402::Types::Verify::PaymentRequirements: Requirements for a payment
• X402::Types::Verify::PaymentPayload: Signed payment data
• X402::Types::Verify::VerifyResponse: Result of payment verification
• X402::Types::Verify::SettleResponse: Result of payment settlement

Client Methods

• X402::Client.create_payment_header: Creates a payment header for a request
• X402::Client.select_payment_requirements: Selects appropriate payment requirements
• X402::Client.prepare_payment_header: Prepares a payment header (without signing)
• X402::Client.sign_payment_header: Signs a payment header

Facilitator Methods

• X402::Facilitator.verify: Verifies a payment payload against requirements
• X402::Facilitator.settle: Settles a verified payment
• X402::Facilitator.supported: Returns supported schemes and networks

Configuration

You can configure the x402 implementation with a config object:

config = X402::Types::X402Config.new(
  svm_config: X402::Types::SvmConfig.new(rpc_url: "https://your-solana-rpc.com")
)

Contributing

1. Fork it (https://github.com/your-github-user/x402-crystal/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• [Your Name] - creator and maintainer