x402 Go Infrastructure

Repository: github.com/denizumutdereli/x402

This repository contains a self-hosted x402 infrastructure foundation built in Go.

The current implementation is designed to reuse the upstream coinbase/x402/go protocol logic instead of reimplementing payment verification, signing, and settlement rules from scratch. This repository adds an application and infrastructure layer around that core: service composition, configuration, HTTP APIs, trusted setup registration, and testable local development flows.

Current Status

This project is currently a working foundation, not a fully finished production platform.

At the moment, the repository includes:

• A self-hosted facilitator service
• A self-hosted resource server service
• A flexible JSON configuration model
• A mock EVM trusted setup for deterministic local testing
• A real EVM signer path for RPC-backed settlement flows
• Unit tests for configuration and internal guard behavior
• A full end-to-end happy path test for the x402 payment flow

What This Repository Is Responsible For

This monorepo provides the infrastructure and application shell around x402:

• Service bootstrapping
• HTTP APIs
• Config loading and validation
• Trusted setup registration
• Payment middleware wiring
• Facilitator authentication
• Local test harnesses
• End-to-end orchestration

What Is Reused from Upstream x402

The core payment protocol behavior is intentionally reused from upstream libraries, especially:

• Payment requirement parsing
• HTTP x402 payment handling
• EVM exact payment requirement generation
• Signature verification
• Balance and nonce checks
• Settlement flow execution

In other words: this repository owns the infra/application composition, while upstream owns most of the protocol-critical x402 logic.

Repository Structure

.
├── cmd/
│   ├── facilitator/
│   └── resource-server/
├── configs/
│   ├── facilitator.example.json
│   └── resource-server.example.json
├── e2e/
│   └── e2e_test.go
├── internal/
│   ├── auth/
│   ├── config/
│   ├── facilitator/
│   └── resourceserver/
└── resources/
    └── coinbase-x402/

Main Components

1. Facilitator

The facilitator is the service responsible for verifying and settling payments.

Main files:

• cmd/facilitator/main.go
• internal/facilitator/app.go
• internal/facilitator/mock_evm.go
• internal/facilitator/real_evm.go
• internal/facilitator/guard.go

Responsibilities:

• Expose GET /health
• Expose GET /supported
• Expose POST /verify
• Expose POST /settle
• Validate inbound facilitator requests
• Authenticate callers with optional bearer auth
• Register trusted setups by network
• Delegate actual verify/settle logic to upstream x402 mechanisms
• Enforce verify-before-settle ordering with a short-lived in-memory guard

2. Resource Server

The resource server protects application routes and requires x402 payments before returning paid responses.

Main files:

• cmd/resource-server/main.go
• internal/resourceserver/http.go

Responsibilities:

• Load route and payment definitions from config
• Build upstream x402 HTTP payment middleware
• Return 402 Payment Required when payment is missing or invalid
• Call the facilitator to verify incoming payments
• Run the protected handler/response logic after verification
• Trigger settlement after the protected response is successfully generated

3. Configuration Layer

Main file:

• internal/config/config.go

Responsibilities:

• Load JSON configuration files
• Apply defaults for server timeouts and ports
• Validate route definitions
• Validate payment definitions
• Validate trusted setup definitions
• Support both mock and real EVM trusted setups

4. Auth Layer

Main file:

• internal/auth/bearer.go

Responsibilities:

• Resolve static or environment-based bearer tokens
• Attach auth headers when the resource server calls the facilitator
• Validate incoming facilitator API authentication

5. Local Test Infrastructure

Main files:

• internal/facilitator/mock_evm.go
• e2e/e2e_test.go

Responsibilities:

• Provide deterministic in-memory token balances
• Simulate EVM contract reads and writes for local testing
• Make end-to-end x402 tests runnable without a live blockchain

How the Current App Works

The current flow is built around two services:

• Resource Server: protects routes and asks for payment
• Facilitator: verifies and settles payments

A client requests a paid endpoint from the resource server. If payment is missing, the resource server responds with x402 payment requirements. The client then creates a payment payload, signs it, and retries the request with x402 payment headers. The resource server sends the payment material to the facilitator for verification. If verification succeeds, the resource server produces the protected response and then asks the facilitator to settle the payment.

Who Signs the Payment

The payment is signed by the payer/client signer, not by the facilitator.

In the current test flow, the signer is created using the upstream EVM client signer and signs EIP-712 typed data using the payer private key.

The facilitator verifies that signature and, if everything is valid, executes settlement through the configured trusted setup signer.

Validation Model

Validation happens in multiple layers.

Config Validation

Handled in internal/config/config.go.

This validates:

• Required server values
• Route definitions
• Payment definitions
• Facilitator URL and timeout
• Trusted setup definitions
• RPC/private key settings for real EVM mode

Request Shape Validation

Handled in internal/facilitator/app.go.

This validates that incoming facilitator API requests contain:

• paymentPayload
• paymentRequirements

Payment Validation

Handled primarily by upstream x402 EVM exact facilitator logic.

This includes:

• Recipient checks
• Required amount checks
• Expiration checks
• Nonce checks
• Balance checks
• Signature verification

State and Session Model

There is currently no persistent session store and no user session model.

The only short-lived state currently managed by this repository is a temporary in-memory verify-before-settle guard:

• Successful verification marks a payment as verified for a short TTL
• Settlement requires a matching verified payment entry
• Successful or failed settlement removes the temporary mark

This is useful for a deterministic local flow, but it is not yet a production-grade distributed state model.

x402 Request Lifecycle

sequenceDiagram
    autonumber
    participant Client
    participant ResourceServer
    participant Facilitator
    participant TrustedSetup as Trusted Setup / Signer
    participant Chain as Blockchain / Mock Chain

    Client->>ResourceServer: GET /paid-resource
    ResourceServer->>ResourceServer: Match protected route
    ResourceServer-->>Client: 402 Payment Required + payment requirements

    Client->>Client: Build x402 payment payload
    Client->>Client: Sign EIP-712 authorization with payer key
    Client->>ResourceServer: Retry request with x402 payment headers

    ResourceServer->>Facilitator: POST /verify
    Facilitator->>TrustedSetup: Verify payload, nonce, balance, signature
    TrustedSetup->>Chain: Read state (balance / nonce / code if needed)
    Chain-->>TrustedSetup: Current on-chain or mock state
    TrustedSetup-->>Facilitator: Verify result
    Facilitator-->>ResourceServer: Payment valid

    ResourceServer->>ResourceServer: Produce protected response
    ResourceServer->>Facilitator: POST /settle
    Facilitator->>TrustedSetup: Execute settlement
    TrustedSetup->>Chain: Submit transfer / authorization transaction
    Chain-->>TrustedSetup: Receipt / success
    TrustedSetup-->>Facilitator: Settlement result
    Facilitator-->>ResourceServer: Settlement success
    ResourceServer-->>Client: 200 OK + paid response + payment response headers

Loading

Current Local Development Flow

Run Tests

go test ./...

Run the Facilitator

export FACILITATOR_BEARER_TOKEN=secret-token
go run ./cmd/facilitator -config configs/facilitator.example.json

Run the Resource Server

export FACILITATOR_BEARER_TOKEN=secret-token
go run ./cmd/resource-server -config configs/resource-server.example.json

Quick Checks

curl -i http://localhost:4021/health
curl -i http://localhost:4021/weather

Expected behavior:

• GET /health returns 200 OK
• GET /weather returns 402 Payment Required unless a valid x402 payment is attached

What Has Been Tested So Far

The current test coverage proves the following foundation behavior:

• Config validation works for the current config model
• The in-memory verification guard behaves as expected
• The full x402 happy path works end to end in mock EVM mode

The current end-to-end test covers:

• Facilitator startup
• Resource server startup
• Upstream x402 client integration
• Payment creation and signing
• Verification
• Settlement
• Paid response handling

Upstream and Local References

Local cloned references

• resources/coinbase-x402/examples/go/servers/custom/main.go
• resources/coinbase-x402/go/http/server.go
• resources/coinbase-x402/go/http/client.go
• resources/coinbase-x402/go/http/facilitator_client.go
• resources/coinbase-x402/go/mechanisms/evm/exact/server/scheme.go
• resources/coinbase-x402/go/mechanisms/evm/exact/facilitator/scheme.go
• resources/coinbase-x402/go/signers/evm/client.go
• resources/coinbase-x402/go/types.go
• resources/coinbase-x402/go/types/v2.go

Upstream repository references

• coinbase/x402
• Go examples in coinbase/x402
• Go package in coinbase/x402

Summary

This repository currently gives you a working x402 infrastructure foundation in Go:

• a resource server
• a facilitator
• a config-driven setup model
• a local deterministic mock payment flow
• a real EVM signer integration path
• a tested end-to-end happy path

It is intentionally built to reuse upstream x402 payment mechanics instead of reinventing them, while adding the monorepo structure needed for application composition, local testing, and future production hardening.