Go SDK 参考#

// Network 是 CAIP-2 格式的链标识，例如 "eip155:196"。
type Network string

func ParseNetwork(s string) Network
func (n Network) Match(pattern Network) bool                  // "eip155:1" 匹配 "eip155:*"
func (n Network) Parse() (namespace, reference string, err error)

// Price 可以是 "$0.01" / "0.01" / 数字 / AssetAmount。
type Price interface{}

type AssetAmount struct {
	Asset  string                 `json:"asset"`  // 代币合约地址
	Amount string                 `json:"amount"` // 最小单位金额
	Extra  map[string]interface{} `json:"extra,omitempty"`
}

func IsWildcardNetwork(network Network) bool
func MatchesNetwork(pattern Network, network Network) bool

type ResourceInfo struct {
	URL         string `json:"url"`
	Description string `json:"description,omitempty"`
	MimeType    string `json:"mimeType,omitempty"`
}

type PaymentRequirements struct {
	Scheme            string                 `json:"scheme"`  // "exact" | "aggr_deferred" | "upto"
	Network           string                 `json:"network"` // CAIP-2
	Asset             string                 `json:"asset"`   // 代币合约地址
	Amount            string                 `json:"amount"`  // 价格（upto 时为 cap），最小单位
	PayTo             string                 `json:"payTo"`   // 收款地址
	MaxTimeoutSeconds int                    `json:"maxTimeoutSeconds"`
	Extra             map[string]interface{} `json:"extra,omitempty"` // scheme 专属数据
}

type PaymentRequired struct {
	X402Version int                    `json:"x402Version"`
	Error       string                 `json:"error,omitempty"`
	Resource    *ResourceInfo          `json:"resource,omitempty"`
	Accepts     []PaymentRequirements  `json:"accepts"`
	Extensions  map[string]interface{} `json:"extensions,omitempty"`
}

type PaymentPayload struct {
	X402Version int                    `json:"x402Version"`
	Payload     map[string]interface{} `json:"payload"`  // 详见下方 EVM Payload 一节
	Accepted    PaymentRequirements    `json:"accepted"`
	Resource    *ResourceInfo          `json:"resource,omitempty"`
	Extensions  map[string]interface{} `json:"extensions,omitempty"`
}

func (p PaymentPayload) GetVersion() int
func (p PaymentPayload) GetScheme() string
func (p PaymentPayload) GetNetwork() string
func (p PaymentPayload) GetPayload() map[string]interface{}

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

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"`        // 交易哈希（aggr_deferred 为空）
	Network      Network `json:"network"`
	Status       string  `json:"status,omitempty"`   // OKX 扩展: "pending" | "success" | "timeout"
	// upto 等场景下实际结算金额可能严格小于签名 cap。
	Amount       string  `json:"amount,omitempty"`
}

type SupportedKind struct {
	X402Version int                    `json:"x402Version"`
	Scheme      string                 `json:"scheme"`
	Network     string                 `json:"network"`
	// upto: facilitator 地址通过 extra.facilitatorAddress 暴露；卖方 scheme
	// 会在 EnhancePaymentRequirements 时把它注入 challenge 的 extra。
	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 → signer 地址
}

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

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)
}

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)
}

// 可选接口：支持按交易哈希查询结算状态（用于 timeout 恢复轮询）。
type SettleStatusChecker interface {
	GetSettleStatus(ctx context.Context, txHash string) (*SettleStatusResponse, error)
}

// 在 types 包。
type ResourceServerExtension interface {
	Key() string
	EnrichDeclaration(declaration interface{}, transportContext interface{}) interface{}
}

// 在 x402 包，facilitator 侧扩展。
type FacilitatorExtension interface {
	Key() string
}
func NewFacilitatorExtension(key string) FacilitatorExtension

import (
	"github.com/okx/payments/go/x402"
	exact "github.com/okx/payments/go/x402/mechanisms/evm/exact/server"
	deferred "github.com/okx/payments/go/x402/mechanisms/evm/deferred/server"
	uptoserver "github.com/okx/payments/go/x402/mechanisms/evm/upto/server"
)

server := x402.Newx402ResourceServer(
	x402.WithFacilitatorClient(fac),
).
	Register("eip155:196", exact.NewExactEvmScheme()).        // exact (EIP-3009 / Permit2)
	Register("eip155:196", deferred.NewAggrDeferredEvmScheme()). // aggr_deferred
	Register("eip155:196", uptoserver.NewUptoEvmScheme())     // upto (cap + override)

type ResourceServerOption func(*x402ResourceServer)

func WithFacilitatorClient(client FacilitatorClient) ResourceServerOption
func WithSchemeServer(network Network, schemeServer SchemeNetworkServer) ResourceServerOption // 等价于链式 Register
func WithCacheTTL(ttl time.Duration) ResourceServerOption
func WithBeforeVerifyHook(hook BeforeVerifyHook) ResourceServerOption
func WithAfterVerifyHook(hook AfterVerifyHook) ResourceServerOption
func WithOnVerifyFailureHook(hook OnVerifyFailureHook) ResourceServerOption
func WithBeforeSettleHook(hook BeforeSettleHook) ResourceServerOption
func WithAfterSettleHook(hook AfterSettleHook) ResourceServerOption
func WithOnSettleFailureHook(hook OnSettleFailureHook) ResourceServerOption

func Newx402ResourceServer(opts ...ResourceServerOption) *x402ResourceServer

func (s *x402ResourceServer) Register(network Network, schemeServer SchemeNetworkServer) *x402ResourceServer
func (s *x402ResourceServer) RegisterExtension(extension types.ResourceServerExtension) *x402ResourceServer

// 拉取 facilitator 的 supported kinds 并缓存。initialize 不是可选的：
// HTTP 层会在中间件挂载/首次请求时驱动它（见下）。
func (s *x402ResourceServer) Initialize(ctx context.Context) error

func (s *x402ResourceServer) HasRegisteredScheme(network Network, scheme string) bool
func (s *x402ResourceServer) HasFacilitatorSupport(network Network, scheme string) bool
func (s *x402ResourceServer) GetFacilitatorClient(network Network, scheme string) FacilitatorClient

// 用一份 ResourceConfig + supportedKind 生成 challenge（内部会调度对应 scheme 的
// ParsePrice + EnhancePaymentRequirements）。
func (s *x402ResourceServer) BuildPaymentRequirements(
	ctx context.Context,
	config ResourceConfig,
	supportedKind types.SupportedKind,
	extensions []string,
) (types.PaymentRequirements, error)

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

// overrides: upto scheme 用——业务 handler 决定本次实际扣款金额（≤ cap），
// 通过响应头透传给中间件，中间件解析为 *SettlementOverrides 后调本接口。
func (s *x402ResourceServer) SettlePayment(
	ctx context.Context,
	payload types.PaymentPayload,
	requirements types.PaymentRequirements,
	overrides *SettlementOverrides,
) (*SettleResponse, error)

func (s *x402ResourceServer) FindMatchingRequirements(
	available []types.PaymentRequirements,
	payload types.PaymentPayload,
) *types.PaymentRequirements

type PollResult string
const (
	PollResultSuccess PollResult = "success"
	PollResultFailed  PollResult = "failed"
	PollResultTimeout PollResult = "timeout"
)

type ResourceConfig struct {
	Scheme            string                 `json:"scheme"`
	PayTo             string                 `json:"payTo"`
	Price             Price                  `json:"price"`
	Network           Network                `json:"network"`
	MaxTimeoutSeconds int                    `json:"maxTimeoutSeconds,omitempty"`
	Extra             map[string]interface{} `json:"extra,omitempty"`
}

// 由业务 handler 通过响应头设置；中间件读出后在 settle 时应用。
type SettlementOverrides struct {
	// 实际结算金额（原子单位），必须 <= 授权 cap。
	Amount string `json:"amount,omitempty"`
}

import x402http "github.com/okx/payments/go/x402/http"

syncSettle := true
fac, err := x402http.NewOKXFacilitatorClient(&x402http.OKXFacilitatorConfig{
	Auth: x402http.OKXAuthConfig{
		APIKey:     apiKey,
		SecretKey:  secretKey,
		Passphrase: passphrase,
		// BaseURL / BasePath 可选
	},
	BaseURL:    "https://web3.okx.com", // 默认值；sandbox/staging 可覆盖
	SyncSettle: &syncSettle,            // 默认 true：等链上确认后返回（exact）
})

type OKXAuthConfig struct {
	APIKey     string
	SecretKey  string
	Passphrase string
	BaseURL    string // 默认 "https://web3.okx.com"
	BasePath   string // 例如 "/api/v6/x402"
}

type OKXFacilitatorConfig struct {
	Auth       OKXAuthConfig
	BaseURL    string        // 默认 "https://web3.okx.com"
	SyncSettle *bool         // 默认 true
	HTTPClient *http.Client
	Timeout    time.Duration
}

func NewOKXFacilitatorClient(config *OKXFacilitatorConfig) (*OKXFacilitatorClient, error)

func (c *OKXFacilitatorClient) GetSupported(ctx context.Context) (x402.SupportedResponse, error)
func (c *OKXFacilitatorClient) Verify(ctx context.Context, payloadBytes []byte, requirementsBytes []byte) (*x402.VerifyResponse, error)
func (c *OKXFacilitatorClient) Settle(ctx context.Context, payloadBytes []byte, requirementsBytes []byte) (*x402.SettleResponse, error)
func (c *OKXFacilitatorClient) GetSettleStatus(ctx context.Context, txHash string) (*x402.SettleStatusResponse, error)

type FacilitatorConfig struct {
	URL          string
	HTTPClient   *http.Client
	AuthProvider AuthProvider
	Timeout      time.Duration // 默认 30s
	Identifier   string
}

func NewHTTPFacilitatorClient(config *FacilitatorConfig) *HTTPFacilitatorClient
func NewFacilitatorClient(config *FacilitatorConfig) *HTTPFacilitatorClient // 别名

const DefaultFacilitatorURL = "https://x402.org/facilitator"

// 计算 OKX 签名: Base64(HMAC-SHA256(secret, timestamp + METHOD + path + body))。
func ComputeSignature(secretKey, timestamp, method, path, body string) string

type AuthProvider interface {
	GetAuthHeaders(ctx context.Context) (AuthHeaders, error)
}

type AuthHeaders struct {
	// 各端点的认证头集合
}

// http 包
const DefaultPollInterval = 1 * time.Second
const DefaultPollDeadline = 5 * time.Second
const SettlementOverridesHeader = "settlement-overrides"

const (
	ResultNoPaymentRequired = "no-payment-required"
	ResultPaymentVerified   = "payment-verified"
	ResultPaymentError      = "payment-error"
)

type RoutesConfig map[string]RouteConfig

type RouteConfig struct {
	Accepts PaymentOptions `json:"accepts"`

	Resource          string                 `json:"resource,omitempty"`    // 手动钉死 ResourceInfo.url；为空时按请求自动拼
	Description       string                 `json:"description,omitempty"`
	MimeType          string                 `json:"mimeType,omitempty"`
	CustomPaywallHTML string                 `json:"customPaywallHtml,omitempty"`
	Extensions        map[string]interface{} `json:"extensions,omitempty"`
	AcceptedDomains   []string               `json:"acceptedDomains,omitempty"` // payload.resource.url host 白名单（容忍反代/CDN 改写 Host）
	UnpaidResponseBody UnpaidResponseBodyFunc `json:"-"`                         // 自定义未付费响应体
}

type PaymentOptions = []PaymentOption

type PaymentOption struct {
	Scheme            string                 `json:"scheme"`            // "exact" | "aggr_deferred" | "upto"
	PayTo             interface{}            `json:"payTo"`             // string 或 DynamicPayToFunc
	Price             interface{}            `json:"price"`             // x402.Price 或 DynamicPriceFunc
	Network           x402.Network           `json:"network"`
	MaxTimeoutSeconds int                    `json:"maxTimeoutSeconds,omitempty"`
	Extra             map[string]interface{} `json:"extra,omitempty"`
}

// PayTo / Price 支持运行时动态求值。
type DynamicPayToFunc func(context.Context, HTTPRequestContext) (string, error)
type DynamicPriceFunc func(context.Context, HTTPRequestContext) (x402.Price, error)

routes := x402http.RoutesConfig{
	"GET /api/data": {
		Accepts: x402http.PaymentOptions{
			// 1) 默认 exact + EIP-3009（X Layer 上的 USD₮0）
			{
				Scheme:  "exact",
				Price:   "$0.01",
				Network: "eip155:196",
				PayTo:   "0xSeller",
			},
			// 2) exact + Permit2（通用 ERC-20）
			{
				Scheme:  "exact",
				Price:   "$0.01",
				Network: "eip155:196",
				PayTo:   "0xSeller",
				Extra:   map[string]any{"assetTransferMethod": "permit2"},
			},
			// 3) aggr_deferred（TEE 聚合）
			{
				Scheme:  "aggr_deferred",
				Price:   "$0.001",
				Network: "eip155:196",
				PayTo:   "0xSeller",
			},
		},
		Description: "Premium data",
		MimeType:    "application/json",
	},
}

import (
	nethttpmw "github.com/okx/payments/go/x402/http/nethttp"
	evm "github.com/okx/payments/go/x402/mechanisms/evm/exact/server"
)

mux := http.NewServeMux()
mux.HandleFunc("/api/data", handler)

handler := nethttpmw.X402Payment(nethttpmw.Config{
	Routes:      routes,
	Facilitator: fac,
	Schemes: []nethttpmw.SchemeConfig{
		{Network: "eip155:*", Server: evm.NewExactEvmScheme()},
	},
	SyncFacilitatorOnStart: true,
	Timeout:                30 * time.Second,
})(mux)

func X402Payment(config Config) func(http.Handler) http.Handler

type Config struct {
	Routes                 x402http.RoutesConfig
	Facilitator            x402.FacilitatorClient   // 用 Facilitator 或 Facilitators，二选一
	Facilitators           []x402.FacilitatorClient
	Schemes                []SchemeConfig
	PaywallConfig          *x402http.PaywallConfig
	SyncFacilitatorOnStart bool                     // 默认 true：启动时拉 supported kinds
	Timeout                time.Duration            // 默认 30s
	ErrorHandler           func(w http.ResponseWriter, r *http.Request, err error)
	SettlementHandler      func(w http.ResponseWriter, r *http.Request, resp *x402.SettleResponse)
}

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

// 用预构造好的 server / HTTPServer（便于先挂 hook）：
func PaymentMiddleware(routes x402http.RoutesConfig, server *x402.X402ResourceServer, opts ...MiddlewareOption) func(http.Handler) http.Handler
func PaymentMiddlewareFromHTTPServer(httpServer *x402http.HTTPServer, opts ...MiddlewareOption) func(http.Handler) http.Handler
func PaymentMiddlewareFromConfig(routes x402http.RoutesConfig, opts ...MiddlewareOption) func(http.Handler) http.Handler

// 最小配置版（单路由 + 单 facilitator URL）：
func SimpleX402Payment(payTo string, price string, network x402.Network, facilitatorURL string) func(http.Handler) http.Handler

// 从 handler 内部取已验证的 payload / requirements：
func PayloadFromContext(ctx context.Context) (*types.PaymentPayload, bool)
func RequirementsFromContext(ctx context.Context) (*types.PaymentRequirements, bool)

import ginmw "github.com/okx/payments/go/x402/http/gin"

r.Use(ginmw.X402Payment(ginmw.Config{
	Routes:      routes,
	Facilitator: fac,
	Schemes: []ginmw.SchemeConfig{
		{Network: "eip155:*", Server: evm.NewExactEvmScheme()},
	},
	SyncFacilitatorOnStart: true,
	Timeout:                30 * time.Second,
}))

// 各框架同名函数，签名随框架的 request/response 句柄变化：
func ginmw.SetSettlementOverrides(c *gin.Context, overrides *x402.SettlementOverrides)
func echomw.SetSettlementOverrides(c echo.Context, overrides *x402.SettlementOverrides)
func nethttpmw.SetSettlementOverrides(w http.ResponseWriter, overrides *x402.SettlementOverrides)

// handler 内（upto）——以 Gin 为例：
ginmw.SetSettlementOverrides(c, &x402.SettlementOverrides{Amount: "1234000"})

httpServer := x402http.Wrappedx402HTTPResourceServer(routes, resourceServer).
	OnProtectedRequest(requestHook).
	SetPollDeadline(8 * time.Second).
	OnSettlementTimeout(func(ctx context.Context, txHash, network string) (confirmed bool, err error) {
		// 超时观测：链上二次确认 / 日志 / 上报指标
		return false, nil
	})

func (s *HTTPServer) OnProtectedRequest(hook ProtectedRequestHook) *HTTPServer
func (s *HTTPServer) SetPollDeadline(deadline time.Duration) *HTTPServer
func (s *HTTPServer) OnSettlementTimeout(hook OnSettlementTimeoutHook) *HTTPServer
func (s *HTTPServer) RegisterPaywallProvider(provider PaywallProvider) *HTTPServer
func (s *HTTPServer) AddRoutes(routes RoutesConfig) *HTTPServer
func (s *HTTPServer) Initialize(ctx context.Context) error // 拉 supported kinds + 校验路由配置

// 超时恢复 hook：参数是 (ctx, txHash, network)，返回 confirmed 决定是否交付资源。
type OnSettlementTimeoutHook func(ctx context.Context, txHash string, network string) (confirmed bool, err error)

import exact "github.com/okx/payments/go/x402/mechanisms/evm/exact/server"

scheme := exact.NewExactEvmScheme()
scheme.Scheme() // "exact"

func NewExactEvmScheme() *ExactEvmScheme
func (s *ExactEvmScheme) Scheme() string
func (s *ExactEvmScheme) ParsePrice(price x402.Price, network x402.Network) (x402.AssetAmount, error)
func (s *ExactEvmScheme) EnhancePaymentRequirements(ctx context.Context, requirements types.PaymentRequirements, supportedKind types.SupportedKind, extensionKeys []string) (types.PaymentRequirements, error)
func (s *ExactEvmScheme) ConvertToTokenAmount(decimalAmount string, network string) (string, error)
func (s *ExactEvmScheme) ConvertFromTokenAmount(tokenAmount string, network string) (string, error)
func (s *ExactEvmScheme) GetDisplayAmount(amount string, network string, asset string) (string, error)
func (s *ExactEvmScheme) GetSupportedNetworks() []string
func (s *ExactEvmScheme) ValidatePaymentRequirements(requirements x402.PaymentRequirements) error
func (s *ExactEvmScheme) RegisterMoneyParser(parser x402.MoneyParser) *ExactEvmScheme // 自定义价格→资产换算链

import deferred "github.com/okx/payments/go/x402/mechanisms/evm/deferred/server"

scheme := deferred.NewAggrDeferredEvmScheme()
scheme.Scheme() // "aggr_deferred"

func NewAggrDeferredEvmScheme() *AggrDeferredEvmScheme
func (s *AggrDeferredEvmScheme) Scheme() string // "aggr_deferred"
func (s *AggrDeferredEvmScheme) ParsePrice(price x402.Price, network x402.Network) (x402.AssetAmount, error)
func (s *AggrDeferredEvmScheme) EnhancePaymentRequirements(ctx context.Context, requirements types.PaymentRequirements, supportedKind types.SupportedKind, extensions []string) (types.PaymentRequirements, error)

import uptoserver "github.com/okx/payments/go/x402/mechanisms/evm/upto/server"

scheme := uptoserver.NewUptoEvmScheme()
scheme.Scheme() // "upto"

func NewUptoEvmScheme() *UptoEvmScheme
func (s *UptoEvmScheme) Scheme() string // "upto"
func (s *UptoEvmScheme) ParsePrice(price x402.Price, network x402.Network) (x402.AssetAmount, error)
func (s *UptoEvmScheme) EnhancePaymentRequirements(ctx context.Context, requirements types.PaymentRequirements, supportedKind types.SupportedKind, extensionKeys []string) (types.PaymentRequirements, error)
func (s *UptoEvmScheme) RegisterMoneyParser(parser x402.MoneyParser) *UptoEvmScheme
// ... ConvertToTokenAmount / ConvertFromTokenAmount / GetDisplayAmount / GetSupportedNetworks / ValidatePaymentRequirements 同 exact

// 服务端结构 / 跨字段校验（在 payload 转发给 facilitator 前运行）：
func ValidateUptoPayload(payload types.PaymentPayload, requirements types.PaymentRequirements) error

// Extra key 常量
const AssetTransferMethodKey = "assetTransferMethod"
const ExtraFacilitatorAddressKey = /* re-export from upto/client */

import (
	exactfac "github.com/okx/payments/go/x402/mechanisms/evm/exact/facilitator"
	uptofac "github.com/okx/payments/go/x402/mechanisms/evm/upto/facilitator"
)

// exact：SimulateInSettle 是普通 bool（零值 false，不重跑）。
type exactfac.ExactEvmSchemeConfig struct {
	DeployERC4337WithEIP6492 bool // 自动部署 ERC-4337 智能钱包（EIP-6492）
	SimulateInSettle         bool // settle 时重跑 eth_call 预演（verify 始终预演）
}
func exactfac.NewExactEvmScheme(signer evm.FacilitatorEvmSigner, config *ExactEvmSchemeConfig) *ExactEvmScheme

// upto：SimulateInSettle 是 *bool —— nil ⇒ 默认 true。
type uptofac.UptoEvmSchemeConfig struct {
	SimulateInSettle *bool // settle 时重跑 eth_call 预演；nil ⇒ true，传 *false 关闭
}
func uptofac.NewUptoEvmScheme(signer evm.FacilitatorEvmSigner, config *UptoEvmSchemeConfig) *UptoEvmScheme
// config = nil 时全用默认（SimulateInSettle 默认 true）。

// 底层 Permit2 结算层 config（被 UptoEvmScheme 透传）：
type uptofac.UptoPermit2FacilitatorConfig struct {
	SimulateInSettle *bool // 同上，nil ⇒ true
}

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

// ---- EIP-3009 (default) ----
type ExactEIP3009Authorization struct {
	From        string `json:"from"`
	To          string `json:"to"`
	Value       string `json:"value"`
	ValidAfter  string `json:"validAfter"`
	ValidBefore string `json:"validBefore"`
	Nonce       string `json:"nonce"`
}

type ExactEIP3009Payload struct {
	Signature     string                    `json:"signature,omitempty"`
	Authorization ExactEIP3009Authorization `json:"authorization"`
}
func PayloadFromMap(data map[string]interface{}) (*ExactEIP3009Payload, error)
func (p *ExactEIP3009Payload) ToMap() map[string]interface{}

// v1/v2 在 Go 里是同一结构的别名：
type ExactEvmPayloadV1 = ExactEIP3009Payload
type ExactEvmPayloadV2 = ExactEIP3009Payload

// ---- Exact + Permit2 ----
type Permit2TokenPermissions struct {
	Token  string `json:"token"`
	Amount string `json:"amount"`
}
type Permit2Witness struct {
	To         string `json:"to"`
	ValidAfter string `json:"validAfter"`
}
func (w Permit2Witness) WitnessTypeString() string
type Permit2Authorization struct {
	From      string                  `json:"from"`
	Permitted Permit2TokenPermissions `json:"permitted"`
	Spender   string                  `json:"spender"`
	Nonce     string                  `json:"nonce"`
	Deadline  string                  `json:"deadline"`
	Witness   Permit2Witness          `json:"witness"`
}
func (a Permit2Authorization) WitnessTypeString() string
type ExactPermit2Payload struct {
	Signature            string               `json:"signature"`
	Permit2Authorization Permit2Authorization `json:"permit2Authorization"`
}
func Permit2PayloadFromMap(data map[string]interface{}) (*ExactPermit2Payload, error)
func (p *ExactPermit2Payload) ToMap() map[string]interface{}

// ---- Upto + Permit2 (cap mode) ----
// upto witness 多了 facilitator，让 upto proxy 链上强制 msg.sender == witness.facilitator。
type UptoPermit2Witness struct {
	To          string `json:"to"`
	Facilitator string `json:"facilitator"`
	ValidAfter  string `json:"validAfter"`
}
func (w UptoPermit2Witness) WitnessTypeString() string
type UptoPermit2Authorization struct {
	From      string                  `json:"from"`
	Permitted Permit2TokenPermissions `json:"permitted"` // permitted.amount 是 cap
	Spender   string                  `json:"spender"`
	Nonce     string                  `json:"nonce"`
	Deadline  string                  `json:"deadline"`
	Witness   UptoPermit2Witness      `json:"witness"`
}
func (a UptoPermit2Authorization) WitnessTypeString() string
type UptoPermit2Payload struct {
	Signature            string                   `json:"signature"`
	Permit2Authorization UptoPermit2Authorization `json:"permit2Authorization"`
}
func UptoPermit2PayloadFromMap(data map[string]interface{}) (*UptoPermit2Payload, error)
func (p *UptoPermit2Payload) ToMap() map[string]interface{}

// payload 形状判别：
func IsEIP3009Payload(data map[string]interface{}) bool
func IsPermit2Payload(data map[string]interface{}) bool
func IsUptoPermit2Payload(data map[string]interface{}) bool

// Permit2 是 CREATE2-vanity 部署，每条 EVM 链地址相同。
const PERMIT2Address = "0x000000000022D473030F116dDEE9F6B43aC78BA3"
const MULTICALL3Address = "0xcA11bde05977b3631167028862bE2a173976CA11"

// x402 部署的 Permit2 proxy 合约（vanity 地址）。
const X402ExactPermit2ProxyAddress = "0x402085c248EeA27D92E8b30b2C58ed07f9E20001"
const X402UptoPermit2ProxyAddress  = "0x4020e7393B728A3939659E5732F87fdd8e680002"

// Permit2 witness typehash 字符串——字段顺序 ABI-significant。
const Permit2ExactWitnessTypeString = "Witness(address to,uint256 validAfter)"
const Permit2UptoWitnessTypeString  = "Witness(address to,address facilitator,uint256 validAfter)"

// scheme 名 / 默认参数
const SchemeExact        = "exact"
const SchemeUpto         = "upto"
const SchemeAggrDeferred = "aggr_deferred"
const DefaultDecimals    = 6
const DefaultValidityPeriod = 3600 // 秒

type AssetInfo struct {
	Address             string
	Name                string              // EIP-712 domain name（USD₮0 用 U+20AE）
	Version             string
	Decimals            int
	AssetTransferMethod AssetTransferMethod // 强制 "permit2"
	SupportsEip2612     bool
}
func GetAssetInfo(network string, assetSymbolOrAddress string) (*AssetInfo, error)

type NetworkConfig struct {
	ChainID      *big.Int
	DefaultAsset AssetInfo
}
func GetNetworkConfig(network string) (*NetworkConfig, error)
func GetEvmChainId(network string) (*big.Int, error)

// 预置 chain ID（含 X Layer 主网 eip155:196 与测试网 eip155:1952）：
var ChainIDXLayer        = big.NewInt(196)
var ChainIDXLayerTestnet = big.NewInt(1952)
// 以及 ChainIDBase / ChainIDBaseSepolia / ChainIDStable / ChainIDMonad / ... 见 NetworkConfigs

// 通用支付错误
type PaymentError struct {
	Code    string                 `json:"code"`
	Message string                 `json:"message"`
	Details map[string]interface{} `json:"details,omitempty"`
}
func NewPaymentError(code, message string, details map[string]interface{}) *PaymentError
func (e *PaymentError) Error() string

// 验证失败
type VerifyError struct {
	InvalidReason  string
	Payer          string
	InvalidMessage string
}
func NewVerifyError(reason, payer, message string) *VerifyError

// 结算失败
type SettleError struct {
	ErrorReason  string
	Payer        string
	Network      Network
	Transaction  string
	ErrorMessage string
}
func NewSettleError(reason, payer string, network Network, transaction, message string) *SettleError

// facilitator 返回了畸形成功体
type FacilitatorResponseError struct { /* 未导出字段 */ } // 在 http 包
func (e *FacilitatorResponseError) Error() string
func (e *FacilitatorResponseError) Unwrap() error

// 路由配置校验错误（HTTPServer.Initialize 返回）
type RouteConfigurationError struct { Errors []RouteValidationError }
type RouteValidationError struct {
	RoutePattern string
	Scheme       string
	Network      x402.Network
	Reason       string // "missing_scheme" | "missing_facilitator"
	Message      string
}

const (
	ErrCodeInvalidPayment     = "invalid_payment"
	ErrCodePaymentRequired    = "payment_required"
	ErrCodeInsufficientFunds  = "insufficient_funds"
	ErrCodeNetworkMismatch    = "network_mismatch"
	ErrCodeSchemeMismatch     = "scheme_mismatch"
	ErrCodeSignatureInvalid   = "signature_invalid"
	ErrCodePaymentExpired     = "payment_expired"
	ErrCodeSettlementFailed   = "settlement_failed"
	ErrCodeUnsupportedScheme  = "unsupported_scheme"
	ErrCodeUnsupportedNetwork = "unsupported_network"
)

func DeepEqual(a, b interface{}) bool
func IsWildcardNetwork(network Network) bool
func MatchesNetwork(pattern Network, network Network) bool

// payload.resource.url 与请求 URL 的匹配（可选 host 白名单容忍反代改写）。
func ResourceMatches(payloadURL, requestURL string, acceptedDomains []string) bool

func ValidatePaymentRequirements(r PaymentRequirements) error
func ValidatePaymentPayload(p PaymentPayload) error // 版本感知：v1/v2 通吃

// X Layer mainnet chain ID。
const evm.XLayerChainID uint64 = 196

// X Layer mainnet escrow 合约地址（不传 EscrowContract 时的兜底）。
const evm.DefaultEscrowContract = "0x5E550002e64FaF79B41D89fE8439eEb1be66CE3b"

// EIP-712 voucher 签名 domain（不显式覆盖时的默认值）。
const evm.DefaultDomainName    = "EVM Payment Channel"
const evm.DefaultDomainVersion = "1"

// challenge 默认有效期（分钟）。
const evm.DefaultExpiresMinutes = 5

// method / intent 名。
const evm.MethodNameEVM = "evm"

// session action 常量。
const evm.ActionOpen, evm.ActionTopUp, evm.ActionVoucher, evm.ActionClose, evm.ActionSettle = "open", "topUp", "voucher", "close", "settle"

// session receipt status 常量。
const evm.StatusOpen, evm.StatusClosed = "open", "closed"

// 最大分账路数。
const evm.MaxSplits = 10

type saclient.SAResponse struct {
    Code int             `json:"code"`
    Msg  string          `json:"msg"`
    Data json.RawMessage `json:"data"`
}

type evm.EVMMethodDetails struct {
    ChainID  *uint64 `json:"chainId,omitempty"`
    FeePayer *bool   `json:"feePayer,omitempty"`   // server pays gas（transaction 模式）
    Memo     *string `json:"memo,omitempty"`
    Splits   []Split `json:"splits,omitempty"`
    // ResourceURL —— 本 charge 保护的 endpoint URL（如 "https://api.shop.com/photo"）。
    // 原样透传到 challenge.request 交给 SA，让商户按 URL 聚合交易量 / 营收。
    // 商户持有；SDK 不自动填。仅 Charge 模式；Session 模式不支持（一个 session
    // 可能横跨多个 URL）。
    ResourceURL *string `json:"resourceUrl,omitempty"`
}

func (d *EVMMethodDetails) IsFeePayer() bool
func evm.ParseEVMMethodDetails(methodDetails json.RawMessage) (*EVMMethodDetails, error)

// Constraints: sum(splits[].amount) < totalAmount；primary recipient 必须留正余额；splits ≤ MaxSplits。
type evm.Split struct {
    Amount    string  `json:"amount"`              // base-units integer string
    Memo      *string `json:"memo,omitempty"`
    Recipient string  `json:"recipient"`           // 40-hex 地址
}

type evm.EVMSessionMethodDetails struct {
    EscrowContract  string         `json:"escrowContract"`
    ChannelID       *string        `json:"channelId,omitempty"`
    MinVoucherDelta *string        `json:"minVoucherDelta,omitempty"`
    ChainID         *uint64        `json:"chainId,omitempty"`
    FeePayer        *bool          `json:"feePayer,omitempty"`
    Splits          []SessionSplit `json:"splits,omitempty"`
}

func (d *EVMSessionMethodDetails) IsFeePayer() bool
func evm.ParseEVMSessionMethodDetails(methodDetails json.RawMessage) (*EVMSessionMethodDetails, error)

// Constraints: bps in [1, 9999]；sum(splits[].bps) < 10000。
type evm.SessionSplit struct {
    Recipient string  `json:"recipient"`
    Bps       uint32  `json:"bps"`
    Memo      *string `json:"memo,omitempty"`
}

type saclient.Eip3009Authorization struct {
    Type        string                 `json:"type"`       // always "eip-3009"
    From        string                 `json:"from"`
    To          string                 `json:"to"`
    Value       string                 `json:"value"`
    ValidAfter  string                 `json:"validAfter"`
    ValidBefore string                 `json:"validBefore"`
    Nonce       string                 `json:"nonce"`
    Signature   string                 `json:"signature,omitempty"`
    Splits      []Eip3009Authorization `json:"splits,omitempty"`
}

type saclient.ChargeReceipt struct {
    Method      string `json:"method"`
    Reference   string `json:"reference"`     // on-chain tx hash
    Status      string `json:"status"`
    Timestamp   string `json:"timestamp"`
    ChainID     uint64 `json:"chainId"`
    ChallengeID string `json:"challengeId"`
    ExternalID  string `json:"externalId"`
}

type saclient.SessionReceipt struct {
    Method    string `json:"method"`
    Intent    string `json:"intent"`
    Status    string `json:"status"`
    Timestamp string `json:"timestamp"`
    ChannelID string `json:"channelId"`
    ChainID   uint64 `json:"chainId"`
    Reference string `json:"reference"`
    Deposit   string `json:"deposit"`          // 当前 on-chain known deposit
}

// GET /session/status 的响应。
type saclient.SessionStatus struct {
    ChannelID        string `json:"channelId"`
    Payer            string `json:"payer"`
    Payee            string `json:"payee"`
    Token            string `json:"token"`
    Deposit          string `json:"deposit"`
    CumulativeAmount string `json:"cumulativeAmount"`
    SettledOnChain   string `json:"settledOnChain"`
    RemainingBalance string `json:"remainingBalance"`
    SessionStatus    string `json:"sessionStatus"`   // OPEN, CLOSING, CLOSED
}

type saclient.CredentialRequest[P any] struct {
    Challenge *protocol.ChallengeEcho `json:"challenge,omitempty"`
    Payload   P                       `json:"payload"`
    Source    string                  `json:"source,omitempty"`
}

type saclient.SessionSettlePayload struct {
    Action           string `json:"action,omitempty"`   // "settle"
    ChannelID        string `json:"channelId"`
    CumulativeAmount string `json:"cumulativeAmount"`
    VoucherSignature string `json:"voucherSignature"`   // payer 65-byte r‖s‖v hex
    PayeeSignature   string `json:"payeeSignature"`      // payee 65-byte r‖s‖v hex
    Nonce            string `json:"nonce"`
    Deadline         string `json:"deadline"`
}

type saclient.SessionClosePayload struct {
    Action           string `json:"action,omitempty"`   // "close"
    ChannelID        string `json:"channelId"`
    CumulativeAmount string `json:"cumulativeAmount"`
    VoucherSignature string `json:"voucherSignature"`   // waiver 分支为 ""
    PayeeSignature   string `json:"payeeSignature"`
    Nonce            string `json:"nonce"`
    Deadline         string `json:"deadline"`
}

// 类型别名：各端点用具体 payload 实例化信封。
type saclient.SessionSettleRequest = CredentialRequest[SessionSettlePayload]
type saclient.SessionCloseRequest  = CredentialRequest[SessionClosePayload]
type saclient.SessionOpenRequest   = CredentialRequest[SessionOpenPayload]
type saclient.SessionTopUpRequest  = CredentialRequest[SessionTopUpPayload]
type saclient.ChargeSettleRequest     = CredentialRequest[ChargeTransactionPayload]
type saclient.ChargeVerifyHashRequest = CredentialRequest[ChargeHashPayload]

type saclient.SAClient interface {
    // Charge（client-facing —— 透传 credential）
    Settle(ctx context.Context, req *ChargeSettleRequest) (*ChargeReceipt, error)
    VerifyHash(ctx context.Context, req *ChargeVerifyHashRequest) (*ChargeReceipt, error)

    // Session（client-facing —— 透传 credential）
    SessionOpen(ctx context.Context, req *SessionOpenRequest) (*SessionReceipt, error)
    SessionTopUp(ctx context.Context, req *SessionTopUpRequest) (*SessionReceipt, error)

    // Session（merchant-facing —— server 构造 request）
    SessionSettle(ctx context.Context, req *SessionSettleRequest) (*SessionReceipt, error)
    SessionClose(ctx context.Context, req *SessionCloseRequest) (*SessionReceipt, error)

    // Session（read-only）
    SessionStatus(ctx context.Context, channelID string) (*SessionStatus, error)
}

type saclient.OKXSAClient struct { /* private */ }

func saclient.NewOKXSAClient(baseURL, apiKey, secretKey, passphrase string, opts ...Option) *OKXSAClient

// functional option。
type saclient.Option func(*OKXSAClient)
func saclient.WithHTTPClient(c *http.Client) Option   // 替换默认 http.Client

func saclient.NewMockSAClient(chainID uint64) *MockSAClient

type evm.EVMChargeMethod struct { /* private */ }

h
func evm.NewEVMChargeMethod() *EVMChargeMethod

func (m *EVMChargeMethod) WithChainID(chainID uint64) *EVMChargeMethod
func (m *EVMChargeMethod) WithRecipient(recipient string) *EVMChargeMethod
func (m *EVMChargeMethod) WithSAClient(c saclient.SAClient) *EVMChargeMethod  // nil → local-only 模式
func (m *EVMChargeMethod) WithFeePayer(feePayer bool) *EVMChargeMethod        // true → transaction 模式

// protocol.ChargeVerifier 实现：
func (m *EVMChargeMethod) Method() string
func (m *EVMChargeMethod) ChallengeMethodDetails() *EVMMethodDetails
func (m *EVMChargeMethod) PrepareRequest(request protocol.ChargeRequest, _ *protocol.PaymentCredential) protocol.ChargeRequest
func (m *EVMChargeMethod) Verify(ctx context.Context, cred *protocol.PaymentCredential, request *protocol.ChargeRequest) (*protocol.Receipt, error)

type evm.EVMSessionMethod struct { /* private */ }

func evm.NewEVMSessionMethod(cfg EVMSessionMethodConfig) (*EVMSessionMethod, error)

type evm.EVMSessionMethodConfig struct {
    // 必填。
    Recipient string            // payee 钱包地址
    SAClient  saclient.SAClient // SA-API client

    // 可选（零值 = 默认）。
    ChainID         uint64                          // 默认 196 (X Layer)
    EscrowContract  string                          // 默认 DefaultEscrowContract
    Signer          Signer                          // payee 签名器；nil → settle/close 关闭
    Store           store.Store[store.ChannelState] // 默认 in-memory store
    PerRequestCost  *big.Int                        // 每次请求扣费额
    MinVoucherDelta *big.Int                        // voucher 最小递增量
    NonceProvider   NonceProvider                   // 默认 UuidNonceProvider
    Deadline        *big.Int                        // 默认 U256 MAX（永不过期）
    DomainName      string                          // 默认 "EVM Payment Channel"
    DomainVersion   string                          // 默认 "1"
    FeePayer        bool                            // payee 是否代付 gas
}

func (m *EVMSessionMethod) Method() string
func (m *EVMSessionMethod) ChallengeMethodDetails() json.RawMessage  // 无 escrow 配置时返 nil
func (m *EVMSessionMethod) VerifySession(ctx context.Context, cred *protocol.PaymentCredential, request *protocol.SessionRequest) (*protocol.Receipt, error)
func (m *EVMSessionMethod) Respond(cred *protocol.PaymentCredential, receipt *protocol.Receipt) any

// 底层 channel store。
func (m *EVMSessionMethod) ChannelStore() store.Store[store.ChannelState]

// 原子扣费：available = highestVoucher - spent；不足返 insufficient-balance 错误。
func (m *EVMSessionMethod) DeductFromSession(ctx context.Context, channelID string, amount *big.Int) (*store.ChannelState, error)

// 取本地 highest voucher → 签 SettleAuthorization → 调 /session/settle。
func (m *EVMSessionMethod) SettleWithAuthorization(ctx context.Context, channelID string) (*saclient.SessionReceipt, error)

// 签 CloseAuthorization → 调 /session/close → 成功后从 store 移除。
func (m *EVMSessionMethod) CloseWithAuthorization(ctx context.Context, channelID string) (*saclient.SessionReceipt, error)

type store.Store[T any] interface {
    Get(ctx context.Context, key string) (*T, error)   // 不存在返 (nil, nil)
    Put(ctx context.Context, key string, value *T) error
    Delete(ctx context.Context, key string) error
}

// 原子扣费 helper：
// 读 channel → 检查约束 → 更新 Spent → 写回。
func store.DeductFromChannel(ctx context.Context, s Store[ChannelState], channelID string, amount *big.Int) (*ChannelState, error)

type store.ChannelState struct {
    ChannelID               string   `json:"channelId"`
    ChainID                 uint64   `json:"chainId"`
    EscrowContract          string   `json:"escrowContract"`
    Payer                   string   `json:"payer"`
    Payee                   string   `json:"payee"`
    Token                   string   `json:"token"`
    AuthorizedSigner        string   `json:"authorizedSigner"`   // open 时 address(0) → payer
    Deposit                 *big.Int `json:"deposit"`
    HighestVoucherAmount    *big.Int `json:"highestVoucherAmount"`
    HighestVoucherSignature []byte   `json:"highestVoucherSignature,omitempty"`
    MinVoucherDelta         *big.Int `json:"minVoucherDelta,omitempty"`   // nil 关闭节流
    Spent                   *big.Int `json:"spent"`               // invariant: spent ≤ highestVoucherAmount
    Units                   uint64   `json:"units"`               // deduct 次数
    Finalized               bool     `json:"finalized"`
    CloseRequestedAt        uint64   `json:"closeRequestedAt"`
    CreatedAt               string   `json:"createdAt"`
}

// 链上视图（SA 拉回的 on-chain channel）。
type store.OnChainChannel struct {
    Payer            string   `json:"payer"`
    Payee            string   `json:"payee"`
    Token            string   `json:"token"`
    AuthorizedSigner string   `json:"authorizedSigner"`
    Deposit          *big.Int `json:"deposit"`
    Settled          *big.Int `json:"settled"`
    CloseRequestedAt uint64   `json:"closeRequestedAt"`
    Finalized        bool     `json:"finalized"`
}

// 默认：进程内 map，值经 JSON round-trip 深拷贝防止 caller 篡改。
type store.MemoryStore[T any] struct { /* private */ }
func store.NewMemoryStore[T any]() *MemoryStore[T]

// 文件持久化：每个 key 一个 JSON 文件，per-key mutex 保证同 key 并发安全。
type store.FileStore[T any] struct { /* private */ }
func store.NewFileStore[T any](dir string) (*FileStore[T], error)  // 自动创建目录

chStore, err := store.NewFileStore[store.ChannelState]("/var/lib/mpp/channels")

type evm.NonceProvider interface {
    Allocate(payee common.Address, channelID [32]byte) (*big.Int, error)
}

// 默认实现：UUID v4 → big.Int（128-bit random，stateless，跨多实例 / 重启安全）。
type evm.UuidNonceProvider struct{}
func evm.NewUuidNonceProvider() *UuidNonceProvider
func (p *UuidNonceProvider) Allocate(_ common.Address, _ [32]byte) (*big.Int, error)

type evm.Signer interface {
    Sign(hash []byte) ([]byte, error)
    SignTypedData(typedData apitypes.TypedData) ([]byte, error)
    Address() common.Address
}

type evm.PrivateKeySigner struct { /* private */ }
func evm.NewPrivateKeySigner(key *ecdsa.PrivateKey) *PrivateKeySigner
func evm.NewPrivateKeySignerFromHex(hexKey string) (*PrivateKeySigner, error)  // 带或不带 "0x"

// EIP-712 voucher 结构 1:1 对应合约的 Voucher{ bytes32 channelId; uint128 cumulativeAmount }。
func evm.SignVoucher(
    signer Signer,
    channelID [32]byte,
    cumulativeAmount *big.Int,
    escrowContract common.Address,
    chainID uint64,
    domainName, domainVersion string,   // 空 → DefaultDomainName / DefaultDomainVersion
) ([]byte, error)                       // 65-byte 签名，v 编为 27/28

// 1) len == 65  2) low-s precheck  3) EIP-712 digest  4) ecrecover + 严格地址比较。
func evm.VerifyVoucher(
    escrowContract common.Address,
    chainID uint64,
    channelID [32]byte,
    cumulativeAmount *big.Int,
    sig []byte,
    expectedSigner common.Address,
    domainName, domainVersion string,
) bool                                  // v 接受 27/28 或 0/1

func evm.ValidateVoucherSignature(sig []byte) error   // 65 字节 + low-s 检查

type evm.SignedAuthorization struct {
    ChannelID        [32]byte
    CumulativeAmount *big.Int
    Nonce            *big.Int
    Deadline         *big.Int
    Signature        []byte    // 65-byte r||s||v
}

// primaryType 选 "SettleAuthorization" 或 "CloseAuthorization"。
func evm.SignAuthorization(
    signer Signer,
    primaryType string,
    channelID [32]byte,
    cumulativeAmount *big.Int,
    nonce *big.Int,
    deadline *big.Int,
    escrowContract common.Address,
    chainID uint64,
    domainName string,
    domainVersion string,
) (*SignedAuthorization, error)

// 确定性 channelId = keccak256(abi.encode(payer, payee, token, salt, authorizedSigner, escrowContract, chainID))。
func evm.ComputeChannelID(
    payer, payee, token common.Address,
    salt [32]byte,
    authorizedSigner, escrowContract common.Address,
    chainID uint64,
) [32]byte

// 从 challenge 解 request。
func protocol.RequestFromChallenge(c *PaymentChallenge) (json.RawMessage, error)
func protocol.RequestFromChallengeTyped(c *PaymentChallenge, v interface{}) error

// 直接对 base64url 串解码。
func protocol.DeserializeRequest(encoded string) (json.RawMessage, error)
func protocol.DeserializeRequestTyped(encoded string, v interface{}) error

// 反向：把 typed request 编成 base64url 串。
func protocol.SerializeRequest(v interface{}) (string, error)

// 用法：
var req protocol.SessionRequest
if err := protocol.RequestFromChallengeTyped(ch, &req); err != nil { /* ... */ }

import mpphttp "github.com/okx/payments/go/mpp/http/nethttp"

// net/http：
func nethttp.ChargeMiddleware(m *server.Mpp, cfg server.ChargeRouteConfig) func(http.Handler) http.Handler
func nethttp.SessionMiddleware(m *server.Mpp, cfg server.SessionRouteConfig) func(http.Handler) http.Handler
func nethttp.GetReceipt(r *http.Request) *protocol.Receipt   // 校验成功后从 ctx 取 receipt

// gin（同名函数，签名换成 gin）：
import mppgin "github.com/okx/payments/go/mpp/http/gin"
func gin.ChargeMiddleware(m *server.Mpp, cfg server.ChargeRouteConfig) gin.HandlerFunc
func gin.SessionMiddleware(m *server.Mpp, cfg server.SessionRouteConfig) gin.HandlerFunc
func gin.GetReceipt(c *gin.Context) *protocol.Receipt

type server.EVMConfig struct {
    ChainID   uint64   // 期望链 ID（196 = X Layer）
    Recipient string   // 期望收款地址（带/不带 0x）
    SecretKey string   // challenge ID 的 HMAC 密钥；空 = 空 key（确定但不认证）
    Realm     string   // WWW-Authenticate realm；空默认 "mpp"
}

type server.Mpp struct { /* private */ }
func server.NewMpp(cfg EVMConfig, charge protocol.ChargeVerifier, session protocol.SessionVerifier) *Mpp
// 两个 verifier 任一可为 nil（只用一种 intent 时）。

// 生成 challenge（返 WWW-Authenticate header 值）：
func (m *Mpp) Charge(ctx context.Context, cfg ChargeRouteConfig) (string, error)
func (m *Mpp) SessionChallenge(ctx context.Context, cfg SessionRouteConfig) (string, error)

// 校验 credential：
func (m *Mpp) VerifyCredential(ctx context.Context, challengeHeader, authHeader string) (*protocol.Receipt, error)
func (m *Mpp) VerifySession(ctx context.Context, challengeHeader, authHeader string) (*protocol.SessionVerifyResult, error)

// 低层变体（自带 request / options）：
func (m *Mpp) ChargeWithOptions(ctx context.Context, req protocol.ChargeRequest, opts ChargeOptions) (string, error)
func (m *Mpp) SessionChallengeWithDetails(ctx context.Context, req protocol.SessionRequest, opts SessionChallengeOptions) (string, error)

type server.ChargeRouteConfig struct {
    Amount      string      // human-readable decimal，如 "0.01"
    Currency    string      // ERC-20 合约地址
    Decimals    uint32      // 代币精度（USDC = 6）
    Description string
    ExternalID  string      // caller 自定义 reference
    Splits      []evm.Split // 次级收款方，主收款方拿 total - sum(splits)；≤ 10
    ResourceURL string      // 【新增】本 charge 保护的 endpoint URL，透传给 SA 按 URL 聚合营收；空则不上报。仅 Charge 模式。
}

type server.SessionRouteConfig struct {
    Amount           string  // human-readable decimal，如 "0.001"
    Currency         string  // ERC-20 合约地址
    Decimals         uint32
    Description      string
    ExternalID       string
    UnitType         string  // 计费单位："request" / "second" / "byte" ...
    SuggestedDeposit string  // 建议初始 deposit（base units）
}

type protocol.VerificationError struct {
    Message   string    `json:"message"`
    Code      ErrorCode `json:"code,omitempty"`
    Retryable bool      `json:"retryable"`
}
func (e *VerificationError) Error() string
func (e *VerificationError) HTTPStatus() int       // 400 / 410 / 402(默认)
func (e *VerificationError) WithRetryable() *VerificationError

// 机器可读错误码（字符串），含 .SpecCode() / .String()：
type protocol.ErrorCode string
const (
    ErrorCodeExpired, ErrorCodeInvalidAmount, ErrorCodeInvalidRecipient,
    ErrorCodeTransactionFailed, ErrorCodeNotFound, ErrorCodeInvalidCredential,
    ErrorCodeNetworkError, ErrorCodeChainIdMismatch, ErrorCodeCredentialMismatch,
    ErrorCodeChannelNotFound, ErrorCodeChannelClosed, ErrorCodeInsufficientBalance,
    ErrorCodeInvalidPayload, ErrorCodeInvalidSignature, ErrorCodeAmountExceedsDeposit,
    ErrorCodeDeltaTooSmall ErrorCode = /* ... */
)
// 配套构造器：protocol.ErrSig / ErrAmount / ErrChannelNotFound / ErrInsufficientBalance / ...
// 以及 VerificationErrorXxx(msg) 一组。

type saclient.SAErrorCode int
const (
    SACodeSuccess              = 0
    SACodeInvalidParams        = 70000   // 缺必填字段或格式错误
    SACodeUnsupportedChain     = 70001   // 链不在支持列表
    SACodePayerBlocked         = 70002   // 付款方在黑名单
    SACodeInvalidCredential    = 70003   // source 缺失 / feePayer=true 不支持 hash 模式 / txHash 已用
    SACodeInvalidSignature     = 70004   // 签名验证失败
    SACodeSplitSumExceedsTotal = 70005   // 分账总额 ≥ 主金额
    SACodeSplitCountExceeded   = 70006   // 分账数量 > 10
    SACodeTxNotConfirmed       = 70007   // 交易未在链上确认
    SACodeChannelClosed        = 70008   // 链上 channel 已关闭
    SACodeChallengeInvalid     = 70009   // challenge 不存在或已过期
    SACodeChannelNotFound      = 70010   // channelId 不存在
    SACodeGracePeriodTooShort  = 70011   // escrow grace period < 10 分钟，拒绝开通
    SACodeAmountExceedsDeposit = 70012   // cumulativeAmount 超 deposit 余额
    SACodeVoucherDeltaTooSmall = 70013   // voucher 递增量低于 minVoucherDelta
    SACodeChannelClosing       = 70014   // channel CLOSING 状态，不收新 voucher
    SACodeInternalError        = 8000    // API 服务内部错误
)

type errors.MppErrorCode string

type errors.MppError struct {
    Code    MppErrorCode `json:"code"`
    Message string       `json:"message"`
    Reason  string       `json:"reason,omitempty"`
}
func (e *MppError) Error() string
func (e *MppError) ToProblemDetails(challengeID string) *PaymentErrorDetails // RFC 9457

type paymentrouter.ProtocolAdapter interface {
    Name() string                                                       // "mpp" | "x402" | 自定义
    Priority() int                                                      // 越小越先 Detect（MPP < x402）
    Detect(r *http.Request) bool                                        // 看请求头是否属于本协议
    GetChallenge(ctx context.Context, r *http.Request, cfg any) (http.Header, error)  // 生成本协议 402 challenge header
    Handle(w http.ResponseWriter, r *http.Request, cfg any) error       // 校验 + 写 receipt / 错误
}

import (
    mppadapters "github.com/okx/payments/go/mpp/adapters"
    x402adapters "github.com/okx/payments/go/x402/adapters"
)

// MppAdapter 接 *server.Mpp（用 server.NewMpp(...) 拼出）。
func mppadapters.NewMppAdapter(mpp *server.Mpp) *MppAdapter
func (a *MppAdapter) Name() string
func (a *MppAdapter) Priority() int
func (a *MppAdapter) Detect(r *http.Request) bool
func (a *MppAdapter) GetChallenge(ctx context.Context, r *http.Request, cfg any) (http.Header, error)
func (a *MppAdapter) Handle(w http.ResponseWriter, r *http.Request, cfg any) error

// X402Adapter 接 *x402http.HTTPServer（routes 可传 nil，由路由 config 懒注册）。
func x402adapters.NewX402Adapter(server *x402http.HTTPServer) *X402Adapter
func (a *X402Adapter) Name() string
func (a *X402Adapter) Priority() int
func (a *X402Adapter) Detect(r *http.Request) bool
func (a *X402Adapter) GetChallenge(ctx context.Context, r *http.Request, cfg any) (http.Header, error)
func (a *X402Adapter) Handle(w http.ResponseWriter, r *http.Request, cfg any) error

// MPP per-route config（MppAdapter 内部 type-assert 到这个类型）。
type mppadapters.MppRouteConfig struct {
    Intent           string `json:"intent"`          // "charge" 或 "session"（空 → "charge"）
    Amount           string `json:"amount"`          // base-units integer string
    Currency         string `json:"currency"`
    Decimals         uint32 `json:"decimals"`
    Description      string `json:"description,omitempty"`
    ExternalID       string `json:"externalId,omitempty"`     // charge only
    Realm            string `json:"realm,omitempty"`
    UnitType         string `json:"unitType,omitempty"`        // session only
    SuggestedDeposit string `json:"suggestedDeposit,omitempty"` // session only
}

// x402 per-route config（X402Adapter 内部 type-assert 到这个类型）。
type x402http.RouteConfig struct {
    Accepts           x402http.PaymentOptions `json:"accepts"`
    Resource          string                  `json:"resource,omitempty"`
    Description       string                  `json:"description,omitempty"`
    MimeType          string                  `json:"mimeType,omitempty"`
    CustomPaywallHTML string                  `json:"customPaywallHtml,omitempty"`
    AcceptedDomains   []string                `json:"acceptedDomains,omitempty"`
    // ... 见 x402 参考
}

import (
    pr "github.com/okx/payments/go/paymentrouter"
    prhttp "github.com/okx/payments/go/paymentrouter/nethttp"
)

// RouteConfig 是 map[adapterName]config —— 没列的 adapter 在本 route 上不启用。
type pr.RouteConfig map[string]any

// 核心 config（用于底层 CompiledRouter / Detect / MergeChallenges）。
type pr.Config struct {
    Routes    []RouteEntry
    Protocols []ProtocolAdapter
    OnError   func(err error, phase, protocol string)
}
type pr.RouteEntry struct {
    Pattern string        // "GET /path" 或 "/path"
    Config  RouteConfig
}

const (
    pr.PhaseDetect    = "detect"
    pr.PhaseChallenge = "challenge"
    pr.PhaseHandle    = "handle"
)

// 启动期校验：route 引用了未注册的 adapter Name → panic（尽早暴露配置错误）。
func pr.ValidateRouteKeys(routes []RouteEntry, protocols []ProtocolAdapter)

// net/http drop-in gate：
type prhttp.PaymentGate struct { /* private */ }
func prhttp.New(protocols []pr.ProtocolAdapter, opts ...Option) *PaymentGate
func (g *PaymentGate) For(cfg pr.RouteConfig) func(http.Handler) http.Handler   // 单 route 的 middleware

type prhttp.Option func(*PaymentGate)
func prhttp.WithOnError(fn func(err error, phase, protocol string)) Option

package main

import (
    "net/http"

    mppadapters "github.com/okx/payments/go/mpp/adapters"
    "github.com/okx/payments/go/mpp/server"
    pr "github.com/okx/payments/go/paymentrouter"
    prhttp "github.com/okx/payments/go/paymentrouter/nethttp"
    x402adapters "github.com/okx/payments/go/x402/adapters"
    x402http "github.com/okx/payments/go/x402/http"
)

func main() {
    // mpp *server.Mpp 与 x402Server *x402http.HTTPServer 按各自参考构造（略）。
    var mpp *server.Mpp
    var x402Server *x402http.HTTPServer

    gate := prhttp.New(
        []pr.ProtocolAdapter{
            mppadapters.NewMppAdapter(mpp),
            x402adapters.NewX402Adapter(x402Server),
        },
        prhttp.WithOnError(func(err error, phase, protocol string) {
            // 记录 detect / challenge / handle 各阶段的协议错误
        }),
    )

    routeCfg := pr.RouteConfig{
        "mpp": mppadapters.MppRouteConfig{
            Intent:   "charge",
            Amount:   "100",
            Currency: "0x...",
            Decimals: 6,
            Description: "photo",
        },
        "x402": x402http.RouteConfig{
            Description: "photo",
            MimeType:    "image/png",
            // Accepts: ... 见 x402 参考
        },
    }

    mux := http.NewServeMux()
    mux.Handle("GET /photo", gate.For(routeCfg)(photoHandler()))
    http.ListenAndServe(":8080", mux)
}

func photoHandler() http.Handler { /* 协议无关的业务 handler */ return nil }