Documentation
¶
Overview ¶
Package buyer implements an x402 buyer sidecar that handles payments using pre-signed ERC-3009 TransferWithAuthorization vouchers. The sidecar acts as an OpenAI-compatible reverse proxy — it intercepts 402 responses from upstream sellers, attaches pre-signed payment headers, and retries automatically.
The agent pre-signs a bounded batch of authorizations and stores them in a ConfigMap. The sidecar reads from this pool and has zero signer access. Spending is bounded by design: max loss = N * price.
Index ¶
- type AuthsFile
- type Config
- type PreSignedAuth
- type PreSignedSigner
- func (s *PreSignedSigner) CanSign(req *x402.PaymentRequirement) bool
- func (s *PreSignedSigner) GetMaxAmount() *big.Int
- func (s *PreSignedSigner) GetPriority() int
- func (s *PreSignedSigner) GetTokens() []x402.TokenConfig
- func (s *PreSignedSigner) Network() string
- func (s *PreSignedSigner) Remaining() int
- func (s *PreSignedSigner) Scheme() string
- func (s *PreSignedSigner) Sign(req *x402.PaymentRequirement) (*x402.PaymentPayload, error)
- func (s *PreSignedSigner) Spent() int
- type Proxy
- type UpstreamConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AuthsFile ¶
type AuthsFile map[string][]*PreSignedAuth
AuthsFile is the top-level structure for the pre-signed authorizations file, loaded from the x402-buyer-auths ConfigMap. Keys are upstream names matching Config.Upstreams.
type Config ¶
type Config struct {
Upstreams map[string]UpstreamConfig `json:"upstreams"`
}
Config is the top-level sidecar configuration, loaded from a JSON file mounted from the x402-buyer-config ConfigMap.
func LoadConfig ¶
LoadConfig reads and parses the sidecar config from a JSON file.
type PreSignedAuth ¶
type PreSignedAuth struct {
Signature string `json:"signature"`
From string `json:"from"`
To string `json:"to"`
Value string `json:"value"`
ValidAfter string `json:"validAfter"`
ValidBefore string `json:"validBefore"`
Nonce string `json:"nonce"`
}
PreSignedAuth is a single pre-signed ERC-3009 TransferWithAuthorization voucher. Each voucher is single-use — consumed when the facilitator calls settle() on-chain.
type PreSignedSigner ¶
type PreSignedSigner struct {
// contains filtered or unexported fields
}
PreSignedSigner implements x402.Signer using pre-signed ERC-3009 TransferWithAuthorization vouchers. It pops one auth from the pool per Sign() call. The pool is finite — once exhausted, CanSign returns false.
Thread-safe via sync.Mutex.
func NewPreSignedSigner ¶
func NewPreSignedSigner(network, payTo, asset, price string, auths []*PreSignedAuth) *PreSignedSigner
NewPreSignedSigner creates a signer backed by a pool of pre-signed auths.
func (*PreSignedSigner) CanSign ¶
func (s *PreSignedSigner) CanSign(req *x402.PaymentRequirement) bool
CanSign checks if this signer can satisfy the given payment requirement. Returns true if network, payTo, asset, and amount match and there are remaining auths in the pool.
func (*PreSignedSigner) GetMaxAmount ¶
func (s *PreSignedSigner) GetMaxAmount() *big.Int
GetMaxAmount returns nil (no per-call limit — bounded by pool size instead).
func (*PreSignedSigner) GetPriority ¶
func (s *PreSignedSigner) GetPriority() int
GetPriority returns 0 (highest priority).
func (*PreSignedSigner) GetTokens ¶
func (s *PreSignedSigner) GetTokens() []x402.TokenConfig
GetTokens returns the single USDC token this signer handles.
func (*PreSignedSigner) Network ¶
func (s *PreSignedSigner) Network() string
Network returns the blockchain network this signer operates on.
func (*PreSignedSigner) Remaining ¶
func (s *PreSignedSigner) Remaining() int
Remaining returns the number of pre-signed authorizations left in the pool.
func (*PreSignedSigner) Scheme ¶
func (s *PreSignedSigner) Scheme() string
Scheme returns "exact" — the only payment scheme for EVM x402.
func (*PreSignedSigner) Sign ¶
func (s *PreSignedSigner) Sign(req *x402.PaymentRequirement) (*x402.PaymentPayload, error)
Sign pops one pre-signed authorization from the pool and returns it as a PaymentPayload. Returns an error when the pool is exhausted.
func (*PreSignedSigner) Spent ¶
func (s *PreSignedSigner) Spent() int
Spent returns the number of authorizations consumed so far.
type Proxy ¶
type Proxy struct {
// contains filtered or unexported fields
}
Proxy is an OpenAI-compatible reverse proxy that routes requests to upstream x402-gated endpoints, attaching pre-signed payment headers automatically.
Routing: /upstream/<name>/v1/... → upstream URL + /v1/...
type UpstreamConfig ¶
type UpstreamConfig struct {
// URL is the upstream base URL (e.g. "https://seller.example.com/services/qwen").
URL string `json:"url"`
// Network is the blockchain network identifier (e.g. "base-sepolia").
Network string `json:"network"`
// PayTo is the seller's receiving address.
PayTo string `json:"payTo"`
// Asset is the token contract address (e.g. USDC on Base Sepolia).
Asset string `json:"asset"`
// Price is the amount in atomic units per request (e.g. "1000" for 0.001 USDC).
Price string `json:"price"`
}
UpstreamConfig describes a single x402-gated upstream endpoint.
Source Files