主题
介绍
功能与服务
核心概念
支持的网络和币种
快速开始
总览
我是卖家
我是买家
支付方式
总览
单次支付
批量支付
SDK 参考
Node.js
Rust
Go
API 参考
认证方式
获取基本信息交易验证交易结算
查询结算状态
公共数据结构
错误码
单次支付与批量支付请求差异
SDK 参考

Go SDK 参考#

包#

包描述
github.com/anthropics/x402/go核心包：客户端、服务端、facilitator、类型定义
.../go/mechanisms/evmEVM 机制：exact、aggr_deferred
.../go/mechanisms/svmSolana 机制：exact
.../go/http/ginGin 中间件（卖方）
.../go/http/echoEcho 中间件（卖方）
.../go/http/nethttpnet/http 中间件（卖方）
.../go/httpHTTP 客户端封装（买方）

核心类型#

Network#

Go
type Network string
// CAIP-2 format, e.g., "eip155:196", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"

func (n Network) Parse() (namespace, reference string, err error)
func (n Network) Match(pattern Network) bool

Price / AssetAmount#

Go
type Price interface{}
// Can be string ("$0.01"), number (0.01), or map (AssetAmount)

type AssetAmount struct {
    Asset  string                 `json:"asset"`    // Token contract address
    Amount string                 `json:"amount"`   // Smallest unit amount
    Extra  map[string]interface{} `json:"extra,omitempty"`
}

ResourceConfig#

Go
type ResourceConfig struct {
    Scheme            string                 `json:"scheme"`            // "exact" | "aggr_deferred" | "upto"
    PayTo             string                 `json:"payTo"`             // Recipient wallet
    Price             Price                  `json:"price"`             // "$0.01" or AssetAmount
    Network           Network                `json:"network"`           // "eip155:196"
    MaxTimeoutSeconds int                    `json:"maxTimeoutSeconds,omitempty"` // Default: 60
    Extra             map[string]interface{} `json:"extra,omitempty"`
}

VerifyResponse#

Go
type VerifyResponse struct {
    IsValid        bool   `json:"isValid"`
    InvalidReason  string `json:"invalidReason,omitempty"`
    InvalidMessage string `json:"invalidMessage,omitempty"`
    Payer          string `json:"payer,omitempty"`
}

SettleResponse#

Go
type SettleResponse struct {
    Success      bool    `json:"success"`
    ErrorReason  string  `json:"errorReason,omitempty"`
    ErrorMessage string  `json:"errorMessage,omitempty"`
    Payer        string  `json:"payer,omitempty"`
    Transaction  string  `json:"transaction"`
    Network      Network `json:"network"`
    Status       string  `json:"status,omitempty"`   // OKX: "pending" | "success" | "timeout"
}

SupportedResponse#

Go
type SupportedKind struct {
    X402Version int                    `json:"x402Version"`
    Scheme      string                 `json:"scheme"`
    Network     Network                `json:"network"`
    Extra       map[string]interface{} `json:"extra,omitempty"`
}

type SupportedResponse struct {
    Kinds      []SupportedKind            `json:"kinds"`
    Extensions []string                   `json:"extensions"`
    Signers    map[string][]string        `json:"signers"` // CAIP family → addresses
}

SettlementOverrides#

Go
type SettlementOverrides struct {
    Amount string `json:"amount,omitempty"` // Atomic units, percentage, or dollar
}

视图接口#

用于 V1/V2 支付数据的统一视图：

Go
type PaymentRequirementsView interface {
    GetScheme() string
    GetNetwork() string
    GetAsset() string
    GetAmount() string
    GetPayTo() string
    GetMaxTimeoutSeconds() int
    GetExtra() map[string]interface{}
}

type PaymentPayloadView interface {
    GetVersion() int
    GetScheme() string
    GetNetwork() string
    GetPayload() map[string]interface{}
}

客户端 API (x402Client)#

构造函数#

Go
import x402 "github.com/anthropics/x402/go"

client := x402.Newx402Client(opts ...ClientOption)

ClientOption 函数：

选项描述
WithPaymentSelector(selector)自定义支付需求选择器
WithPolicy(policy)添加支付过滤策略

注册方法（可链式调用）#

Go
func (c *x402Client) Register(network Network, client SchemeNetworkClient) *x402Client
func (c *x402Client) RegisterV1(network Network, client SchemeNetworkClientV1) *x402Client
func (c *x402Client) RegisterPolicy(policy PaymentPolicy) *x402Client
func (c *x402Client) RegisterExtension(ext ClientExtension) *x402Client

支付创建#

Go
// Select best payment option from requirements list
func (c *x402Client) SelectPaymentRequirements(
    requirements []types.PaymentRequirements,
) (types.PaymentRequirements, error)

// Create signed payment payload
func (c *x402Client) CreatePaymentPayload(
    ctx context.Context,
    requirements types.PaymentRequirements,
    resource *types.ResourceInfo,
    extensions map[string]interface{},
) (types.PaymentPayload, error)

生命周期钩子（可链式调用）#

Go
func (c *x402Client) OnBeforePaymentCreation(hook BeforePaymentCreationHook) *x402Client
func (c *x402Client) OnAfterPaymentCreation(hook AfterPaymentCreationHook) *x402Client
func (c *x402Client) OnPaymentCreationFailure(hook OnPaymentCreationFailureHook) *x402Client

策略与选择器类型#

Go
type PaymentRequirementsSelector func(requirements []PaymentRequirementsView) PaymentRequirementsView
type PaymentPolicy func(requirements []PaymentRequirementsView) []PaymentRequirementsView

func DefaultPaymentSelector(requirements []PaymentRequirementsView) PaymentRequirementsView

服务端 API (x402ResourceServer)#

构造函数#

Go
server := x402.Newx402ResourceServer(opts ...ResourceServerOption)

ResourceServerOption 函数：

选项描述
WithFacilitatorClient(client)设置 facilitator 客户端
WithSchemeServer(network, server)注册一个 scheme
WithCacheTTL(ttl)设置 supported-kinds 缓存 TTL

注册方法（可链式调用）#

Go
func (s *x402ResourceServer) Register(network Network, server SchemeNetworkServer) *x402ResourceServer
func (s *x402ResourceServer) RegisterExtension(ext types.ResourceServerExtension) *x402ResourceServer

初始化#

Go
func (s *x402ResourceServer) Initialize(ctx context.Context) error

支付操作#

Go
// Build requirements from config
func (s *x402ResourceServer) BuildPaymentRequirementsFromConfig(
    ctx context.Context,
    config ResourceConfig,
) ([]types.PaymentRequirements, error)

// Build single requirement
func (s *x402ResourceServer) BuildPaymentRequirements(
    ctx context.Context,
    config ResourceConfig,
    supportedKind types.SupportedKind,
    extensions []string,
) (types.PaymentRequirements, error)

// Create 402 response
func (s *x402ResourceServer) CreatePaymentRequiredResponse(
    requirements []types.PaymentRequirements,
    resourceInfo *types.ResourceInfo,
    errorMsg string,
    extensions map[string]interface{},
) types.PaymentRequired

// Find matching requirements for a payment payload
func (s *x402ResourceServer) FindMatchingRequirements(
    available []types.PaymentRequirements,
    payload types.PaymentPayload,
) *types.PaymentRequirements

// Verify payment signature
func (s *x402ResourceServer) VerifyPayment(
    ctx context.Context,
    payload types.PaymentPayload,
    requirements types.PaymentRequirements,
) (*VerifyResponse, error)

// Settle payment on-chain
func (s *x402ResourceServer) SettlePayment(
    ctx context.Context,
    payload types.PaymentPayload,
    requirements types.PaymentRequirements,
    overrides *SettlementOverrides,
) (*SettleResponse, error)

// Check registered support
func (s *x402ResourceServer) HasRegisteredScheme(network Network, scheme string) bool
func (s *x402ResourceServer) HasFacilitatorSupport(network Network, scheme string) bool

服务端生命周期钩子（可链式调用）#

Go
func (s *x402ResourceServer) OnBeforeVerify(hook BeforeVerifyHook) *x402ResourceServer
func (s *x402ResourceServer) OnAfterVerify(hook AfterVerifyHook) *x402ResourceServer
func (s *x402ResourceServer) OnVerifyFailure(hook OnVerifyFailureHook) *x402ResourceServer
func (s *x402ResourceServer) OnBeforeSettle(hook BeforeSettleHook) *x402ResourceServer
func (s *x402ResourceServer) OnAfterSettle(hook AfterSettleHook) *x402ResourceServer
func (s *x402ResourceServer) OnSettleFailure(hook OnSettleFailureHook) *x402ResourceServer

Scheme 接口#

SchemeNetworkClient（买方）#

Go
type SchemeNetworkClient interface {
    Scheme() string
    CreatePaymentPayload(ctx context.Context, requirements types.PaymentRequirements) (types.PaymentPayload, error)
}

type ExtensionAwareClient interface {
    SchemeNetworkClient
    CreatePaymentPayloadWithExtensions(ctx context.Context, requirements types.PaymentRequirements, extensions map[string]interface{}) (types.PaymentPayload, error)
}

SchemeNetworkServer（卖方）#

Go
type SchemeNetworkServer interface {
    Scheme() string
    ParsePrice(price Price, network Network) (AssetAmount, error)
    EnhancePaymentRequirements(ctx context.Context, requirements types.PaymentRequirements, supportedKind types.SupportedKind, extensions []string) (types.PaymentRequirements, error)
}

SchemeNetworkFacilitator#

Go
type SchemeNetworkFacilitator interface {
    Scheme() string
    CaipFamily() string
    GetExtra(network Network) map[string]interface{}
    GetSigners(network Network) []string
    Verify(ctx context.Context, payload types.PaymentPayload, requirements types.PaymentRequirements, fctx *FacilitatorContext) (*VerifyResponse, error)
    Settle(ctx context.Context, payload types.PaymentPayload, requirements types.PaymentRequirements, fctx *FacilitatorContext) (*SettleResponse, error)
}

FacilitatorClient（网络边界）#

Go
type FacilitatorClient interface {
    Verify(ctx context.Context, payloadBytes []byte, requirementsBytes []byte) (*VerifyResponse, error)
    Settle(ctx context.Context, payloadBytes []byte, requirementsBytes []byte) (*SettleResponse, error)
    GetSupported(ctx context.Context) (SupportedResponse, error)
}

ClientExtension#

Go
type ClientExtension interface {
    Key() string
    EnrichPaymentPayload(ctx context.Context, payload types.PaymentPayload, required types.PaymentRequired) (types.PaymentPayload, error)
}

MoneyParser#

Go
type MoneyParser func(amount float64, network Network) (*AssetAmount, error)

中间件参考#

所有 Go 中间件包提供三个构建层级以及构建器快捷方式。

Gin (go/http/gin)#

Go
import x402gin "github.com/anthropics/x402/go/http/gin"

// Standard (recommended)
r.Use(x402gin.PaymentMiddleware(routes, server, opts ...MiddlewareOption))

// From HTTP server
r.Use(x402gin.PaymentMiddlewareFromHTTPServer(httpServer, opts ...MiddlewareOption))

// From config
r.Use(x402gin.PaymentMiddlewareFromConfig(routes, opts ...MiddlewareOption))

// Builder shortcut
r.Use(x402gin.X402Payment(Config{ Routes: routes, Facilitator: facilitator, Schemes: schemes }))

// Simple one-liner
r.Use(x402gin.SimpleX402Payment(payTo, price, network, facilitatorURL))

MiddlewareOption 函数：

选项类型描述
WithFacilitatorClient(client)FacilitatorClient用于验证/结算的 facilitator
WithScheme(network, server)Network, SchemeNetworkServer注册一个 scheme
WithPaywallConfig(config)*PaywallConfig浏览器付费墙设置
WithSyncFacilitatorOnStart(bool)bool启动时获取支持的 kinds
WithErrorHandler(fn)func(*gin.Context, error)自定义错误处理器
WithSettlementHandler(fn)func(*gin.Context, *SettleResponse)自定义结算处理器
WithTimeout(duration)time.Duration请求超时时间

Config 结构体（构建器模式）：

Go
type Config struct {
    Routes                 x402http.RoutesConfig
    Facilitator            x402.FacilitatorClient
    Facilitators           []x402.FacilitatorClient
    Schemes                []SchemeConfig
    PaywallConfig          *x402http.PaywallConfig
    SyncFacilitatorOnStart bool
    Timeout                time.Duration
    ErrorHandler           func(*gin.Context, error)
    SettlementHandler      func(*gin.Context, *x402.SettleResponse)
}

type SchemeConfig struct {
    Network x402.Network
    Server  x402.SchemeNetworkServer
}

Echo (go/http/echo)#

与 Gin 相同的 API 接口，但使用 echo.Context 类型：

Go
import x402echo "github.com/anthropics/x402/go/http/echo"

e.Use(x402echo.PaymentMiddleware(routes, server, opts ...MiddlewareOption))
e.Use(x402echo.X402Payment(Config{ ... }))
e.Use(x402echo.SimpleX402Payment(payTo, price, network, facilitatorURL))

net/http (go/http/nethttp)#

返回 func(http.Handler) http.Handler：

Go
import x402nethttp "github.com/anthropics/x402/go/http/nethttp"

handler := x402nethttp.PaymentMiddleware(routes, server, opts ...MiddlewareOption)(yourHandler)
handler := x402nethttp.X402Payment(Config{ ... })(yourHandler)
handler := x402nethttp.SimpleX402Payment(payTo, price, network, facilitatorURL)(yourHandler)

http.ListenAndServe(":4021", handler)

HTTP 客户端（买方）#

Go
import x402http "github.com/anthropics/x402/go/http"

// Create HTTP client with payment support
httpClient := x402http.Newx402HTTPClient(x402Client)

// Wrap existing http.Client
wrappedClient := x402http.WrapHTTPClientWithPayment(http.DefaultClient, httpClient)

// Direct methods
resp, err := httpClient.GetWithPayment(ctx, url)
resp, err := httpClient.PostWithPayment(ctx, url, body)
resp, err := httpClient.DoWithPayment(ctx, req)

// Convenience functions
resp, err := x402http.Get(ctx, url, httpClient)
resp, err := x402http.Post(ctx, url, body, httpClient)
resp, err := x402http.Do(ctx, req, httpClient)

EVM 机制#

ExactEvmScheme（客户端）#

Go
import (
    "github.com/anthropics/x402/go/mechanisms/evm"
    evmsigners "github.com/anthropics/x402/go/mechanisms/evm/signers"
    evmclient "github.com/anthropics/x402/go/mechanisms/evm/exact/client"
)

signer, err := evmsigners.NewClientSignerFromPrivateKey("0x...")
scheme := evmclient.NewExactEvmScheme(signer, config)
scheme.Scheme()  // "exact"

ClientEvmSigner 接口：

Go
type ClientEvmSigner interface {
    Address() string
    SignTypedData(ctx context.Context, domain TypedDataDomain, types map[string][]TypedDataField, primaryType string, message map[string]interface{}) ([]byte, error)
}

ExactEvmScheme（服务端）#

Go
import evmserver "github.com/anthropics/x402/go/mechanisms/evm/exact/server"

scheme := evmserver.NewExactEvmScheme()
scheme.RegisterMoneyParser(customParser)  // Optional: custom price parsing
scheme.Scheme()  // "exact"

ExactEvmScheme（Facilitator）#

Go
import evmfacilitator "github.com/anthropics/x402/go/mechanisms/evm/exact/facilitator"

scheme := evmfacilitator.NewExactEvmScheme(signer, &ExactEvmSchemeConfig{
    DeployERC4337WithEIP6492: false,  // Auto-deploy smart wallets
    SimulateInSettle:         false,  // Re-simulate during settle
})

EVM 类型#

Go
type TypedDataDomain struct {
    Name              string   `json:"name"`
    Version           string   `json:"version"`
    ChainID           *big.Int `json:"chainId"`
    VerifyingContract string   `json:"verifyingContract"`
}

type TypedDataField struct {
    Name string `json:"name"`
    Type string `json:"type"`
}

type AssetTransferMethod string
const (
    AssetTransferMethodEIP3009 AssetTransferMethod = "eip3009"
    AssetTransferMethodPermit2 AssetTransferMethod = "permit2"
)

type AssetInfo struct {
    Address             string
    Name                string
    Version             string
    Decimals            int
    AssetTransferMethod AssetTransferMethod
    SupportsEip2612     bool
}

SVM 机制#

ExactSvmScheme（客户端）#

Go
import (
    svmsigners "github.com/anthropics/x402/go/mechanisms/svm/signers"
    svmclient "github.com/anthropics/x402/go/mechanisms/svm/exact/client"
)

signer, err := svmsigners.NewClientSignerFromPrivateKey(solanaPrivateKey)
scheme := svmclient.NewExactSvmScheme(signer, config?)

ExactSvmScheme（服务端）#

Go
import svmserver "github.com/anthropics/x402/go/mechanisms/svm/exact/server"

scheme := svmserver.NewExactSvmScheme()
scheme.RegisterMoneyParser(customParser)

Facilitator 钩子#

Go
type FacilitatorVerifyContext struct {
    Ctx               context.Context
    Payload           PaymentPayloadView
    Requirements      PaymentRequirementsView
    PayloadBytes      []byte
    RequirementsBytes []byte
}

type FacilitatorBeforeHookResult struct {
    Abort   bool
    Reason  string
    Message string
}

type FacilitatorBeforeVerifyHook  func(FacilitatorVerifyContext) (*FacilitatorBeforeHookResult, error)
type FacilitatorAfterVerifyHook   func(FacilitatorVerifyResultContext) error
type FacilitatorOnVerifyFailureHook func(FacilitatorVerifyFailureContext) (*FacilitatorVerifyFailureHookResult, error)
type FacilitatorBeforeSettleHook  func(FacilitatorSettleContext) (*FacilitatorBeforeHookResult, error)
type FacilitatorAfterSettleHook   func(FacilitatorSettleResultContext) error
type FacilitatorOnSettleFailureHook func(FacilitatorSettleFailureContext) (*FacilitatorSettleFailureHookResult, error)
Rust SDK 参考
认证方式
目录