Skip to main content

API Reference

Complete reference for the x402-go packages and APIs.

Facilitator Service Endpoints​

GET /supported​

Returns the list of supported payment schemes and networks.

Response:

{
  "schemes": [
    {
      "scheme": "exact",
      "networks": ["base", "ethereum"]
    }
  ]
}

POST /verify​

Verifies a payment payload without settling.

Request Body:

{
  "payment": "base64_encoded_payment_payload",
  "requirements": {
    "amount": "1000000",
    "asset": "ETH",
    "network": "base",
    "recipient": "0x..."
  }
}

Response:

{
  "valid": true,
  "reason": ""
}

POST /settle​

Settles a verified payment on-chain.

Request Body:

{
  "payment": "base64_encoded_payment_payload"
}

Response:

{
  "success": true,
  "transactionHash": "0x..."
}

Facilitator Client Package​

client.New​

Creates a new facilitator client.

func New(facilitatorURL string) *Client

Parameters:

  • facilitatorURL - URL of the facilitator service

client.GetSupported​

Queries supported payment schemes and networks.

func (c *Client) GetSupported() (*SupportedResponse, error)

client.Verify​

Verifies a payment payload.

func (c *Client) Verify(payment string, requirements Requirements) (*VerifyResponse, error)

Parameters:

  • payment - Base64-encoded payment payload
  • requirements - Payment requirements to verify against

client.Settle​

Settles a payment on-chain.

func (c *Client) Settle(payment string) (*SettleResponse, error)

Parameters:

  • payment - Base64-encoded payment payload

Middleware Package​

middleware.Config​

Configuration for the x402 middleware.

type Config struct {
    FacilitatorURL string // URL of the facilitator service
    PaymentAmount  string // Required payment amount
    PaymentAsset   string // Payment asset (e.g., "ETH", "USDC")
    PaymentNetwork string // Network (e.g., "base", "ethereum")
    Recipient      string // Payment recipient address
}

middleware.X402​

Creates Gin middleware that enforces x402 payments.

func X402(config Config) gin.HandlerFunc

Behavior:

  1. Checks for X-Payment header on incoming requests
  2. If missing, returns 402 Payment Required with payment details
  3. If present, verifies payment with facilitator
  4. If valid, settles payment and allows request to proceed
  5. If invalid, returns 402 with error details

Resource Client Package​

client.New​

Creates a new resource client for making paid requests.

func New(privateKey *ecdsa.PrivateKey) *ResourceClient

Parameters:

  • privateKey - Ethereum private key for signing payments

client.Get​

Makes a GET request, handling payment negotiation.

func (c *ResourceClient) Get(url string) (*http.Response, error)

Behavior:

  1. Makes initial request to the URL
  2. If 402 response, creates and signs payment
  3. Retries request with X-Payment header
  4. Returns final response

client.Post​

Makes a POST request, handling payment negotiation.

func (c *ResourceClient) Post(url string, body io.Reader) (*http.Response, error)

Types​

Requirements​

Payment requirements structure.

type Requirements struct {
    Amount    string `json:"amount"`
    Asset     string `json:"asset"`
    Network   string `json:"network"`
    Recipient string `json:"recipient"`
}

VerifyResponse​

Response from payment verification.

type VerifyResponse struct {
    Valid  bool   `json:"valid"`
    Reason string `json:"reason,omitempty"`
}

SettleResponse​

Response from payment settlement.

type SettleResponse struct {
    Success         bool   `json:"success"`
    TransactionHash string `json:"transactionHash,omitempty"`
    Error           string `json:"error,omitempty"`
}