Skip to main content

Table of Contents

Module spoon_ai.payments

Payment utilities for integrating the SpoonOS core with the x402 payments protocol.

This package wraps the upstream x402 Python SDK with configuration and service abstractions that align to SpoonOS conventions (config.json priority, .env overrides, and async-friendly helper utilities).

Module spoon_ai.payments.server

create_paywalled_router​

def create_paywalled_router(
    service: Optional[X402PaymentService] = None,
    agent_factory: AgentFactory = _default_agent_factory,
    payment_message: str = "Payment required to invoke this agent."
) -> APIRouter

Build a FastAPI router that protects agent invocations behind an x402 paywall.

Arguments:

  • service - Optional pre-configured payment service.
  • agent_factory - Coroutine that returns an initialized agent given its name.
  • payment_message - Message displayed when payment is required.

Returns:

  • APIRouter - Router with /invoke/{agent_name} endpoint ready to mount.

Module spoon_ai.payments.cli

Module spoon_ai.payments.facilitator_client

X402FacilitatorClient Objects​

class X402FacilitatorClient()

Thin wrapper over the upstream facilitator client with async header hooks.

Module spoon_ai.payments.exceptions

X402PaymentError Objects​

class X402PaymentError(Exception)

Base exception for x402 payment operations.

X402ConfigurationError Objects​

class X402ConfigurationError(X402PaymentError)

Raised when integration configuration is invalid or incomplete.

X402VerificationError Objects​

class X402VerificationError(X402PaymentError)

Raised when a payment header fails verification against the facilitator.

X402SettlementError Objects​

class X402SettlementError(X402PaymentError)

Raised when settlement fails or returns an error response.

Module spoon_ai.payments.x402_service

X402PaymentService Objects​

class X402PaymentService()

High level service that aligns the x402 SDK with SpoonOS conventions.

discover_resources​

async def discover_resources(
        *,
        resource_type: Optional[str] = None,
        limit: Optional[int] = None,
        offset: Optional[int] = None) -> ListDiscoveryResourcesResponse

Query the facilitator discovery endpoint for registered paywalled resources.

render_paywall_html​

def render_paywall_html(error: str,
                        request: Optional[X402PaymentRequest] = None,
                        headers: Optional[Dict[str, Any]] = None) -> str

Render the embedded paywall HTML with payment requirements.

build_payment_header​

def build_payment_header(requirements: PaymentRequirements,
                         *,
                         max_value: Optional[int] = None) -> str

Create a signed X-PAYMENT header for outbound requests.

decode_payment_response​

def decode_payment_response(header_value: str) -> X402PaymentReceipt

Decode an X-PAYMENT-RESPONSE header into a structured receipt.

Module spoon_ai.payments.config

X402ConfigurationError Objects​

class X402ConfigurationError(Exception)

Raised when required x402 configuration is missing or invalid.

X402PaywallBranding Objects​

class X402PaywallBranding(BaseModel)

Optional branding customisations for the embedded paywall template.

X402ClientConfig Objects​

class X402ClientConfig(BaseModel)

Holds client-side signing configuration used for outbound payments.

X402Settings Objects​

class X402Settings(BaseModel)

Resolved configuration view for x402 payments inside SpoonOS.

amount_in_atomic_units​

@property
def amount_in_atomic_units() -> str

Return the configured maximum amount encoded as atomic units (string).

build_asset_extra​

def build_asset_extra() -> Dict[str, Any]

Construct the extra payload for the payment requirements.

load​

@classmethod
def load(cls,
         config_manager: Optional[ConfigManager] = None) -> "X402Settings"

Load settings from config.json with .env fallbacks.

Module spoon_ai.payments.app

Module spoon_ai.payments.models

X402PaymentRequest Objects​

class X402PaymentRequest(BaseModel)

Describes a payment requirement that should be issued for a resource.

X402VerifyResult Objects​

class X402VerifyResult(BaseModel)

Captures the facilitator verification response.

X402SettleResult Objects​

class X402SettleResult(BaseModel)

Captures settlement details.

X402PaymentOutcome Objects​

class X402PaymentOutcome(BaseModel)

Aggregates verification and settlement outcomes.

X402PaymentReceipt Objects​

class X402PaymentReceipt(BaseModel)

Decoded representation of the X-PAYMENT-RESPONSE header.