Documentation
¶
Overview ¶
Package buy contains host-side helpers for `obol buy` commands.
Today this is primarily pre-flight logic for `obol buy inference`:
- probe the seller's 402 pricing response
- verify the seller's ERC-8004 registration document against the priced chain
- reject budgets that would exceed the advertised one-request price floor
Signing, PurchaseRequest creation, facilitator interaction, and refill bookkeeping all live inside the agent pod's buy.py — see internal/embed/skills/buy-x402/scripts/buy.py.
Index ¶
- func FetchSellerRegistration(ctx context.Context, sellerURL string) (*erc8004.AgentRegistration, error)
- func ValidateBudgetAgainstPricing(budgetBase string, pricing *PricingResponse) error
- func ValidateTokenAgainstPricing(token string, pricing *PricingResponse) error
- func VerifyAgentID(reg *erc8004.AgentRegistration, expected int64) error
- func VerifyAgentIDForPricing(reg *erc8004.AgentRegistration, expected int64, pricing *PricingResponse) error
- func VerifyAgentIDOnRegistry(reg *erc8004.AgentRegistration, expected int64, expectedRegistry string) error
- func VerifySellerEndpoint(reg *erc8004.AgentRegistration, sellerURL string) error
- type PaymentOption
- type PricingResponse
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FetchSellerRegistration ¶
func FetchSellerRegistration(ctx context.Context, sellerURL string) (*erc8004.AgentRegistration, error)
FetchSellerRegistration fetches and parses the seller's ERC-8004 registration document. sellerURL may be either the seller's base URL (e.g. "https://demo-seller.obol.tech") or a service URL (e.g. ".../services/foo"); the path component is replaced with the well-known path so callers can pass either shape.
func ValidateBudgetAgainstPricing ¶
func ValidateBudgetAgainstPricing(budgetBase string, pricing *PricingResponse) error
ValidateBudgetAgainstPricing rejects budgets smaller than one request price. buy.py currently rounds `budget // price` up to at least one auth; the host CLI advertises --budget as a spending cap, so we fail early instead of silently overspending the requested cap.
Call ValidateTokenAgainstPricing first; this function assumes the token has already been validated against the seller's priced asset.
func ValidateTokenAgainstPricing ¶
func ValidateTokenAgainstPricing(token string, pricing *PricingResponse) error
ValidateTokenAgainstPricing checks that the requested --token matches the seller's priced asset. When there is a mismatch it returns a structured error that names both the requested token and the seller's required asset, and suggests the correct --token value when the asset address is known.
Call this before ValidateBudgetAgainstPricing so the caller sees a clear token-mismatch error instead of a confusing budget-validation failure.
func VerifyAgentID ¶
func VerifyAgentID(reg *erc8004.AgentRegistration, expected int64) error
VerifyAgentID returns nil iff at least one of reg.Registrations matches the expected ERC-8004 tokenId. The seller may publish multiple registrations (one per chain); a match on any of them is sufficient.
func VerifyAgentIDForPricing ¶
func VerifyAgentIDForPricing(reg *erc8004.AgentRegistration, expected int64, pricing *PricingResponse) error
VerifyAgentIDForPricing pins the ERC-8004 identity check to the seller's priced network so a matching tokenId on an unrelated registry does not pass.
func VerifyAgentIDOnRegistry ¶
func VerifyAgentIDOnRegistry(reg *erc8004.AgentRegistration, expected int64, expectedRegistry string) error
VerifyAgentIDOnRegistry requires the expected agentId to appear on the specific CAIP-10 registry identifier resolved from the seller's priced payment network.
func VerifySellerEndpoint ¶
func VerifySellerEndpoint(reg *erc8004.AgentRegistration, sellerURL string) error
VerifySellerEndpoint ensures the requested seller URL is one of the service endpoints advertised in the seller's ERC-8004 registration document.
Types ¶
type PaymentOption ¶
type PaymentOption struct {
PayTo string `json:"payTo"`
Network string `json:"network"`
Asset string `json:"asset"`
Amount string `json:"amount"`
MaxAmountRequired string `json:"maxAmountRequired"`
}
PaymentOption is one entry from the seller's x402 accepts array.
type PricingResponse ¶
type PricingResponse struct {
X402Version int `json:"x402Version"`
Accepts []PaymentOption `json:"accepts"`
}
PricingResponse is the subset of the seller's x402 402 body that the host pre-flight needs before dispatching into buy.py.
func FetchSellerPricing ¶
func FetchSellerPricing(ctx context.Context, sellerURL, model string) (*PricingResponse, error)
FetchSellerPricing probes the seller's chat-completions endpoint and returns the parsed x402 402 body. sellerURL may be either the service root (`.../services/foo`) or the final chat-completions URL.
Source Files