Class X402::Configuration ¶

Inherits: Object

DSL for configuring X402 middleware, gateways, and protected routes.

@example Minimal configuration (relay mode — no keys on server)

X402.configure do |config|
  config.domain = "api.example.com"
  config.operator_wallet_url = "https://my-wallet.example.com/api/server-wallet"
  config.protect method: :GET, path: "/api/expensive", amount_sats: 100
end

Constants¶

BRC105_GATEWAY_KNOWN_OPTS ¶

Not documented.

BRC121_GATEWAY_KNOWN_OPTS ¶

Not documented.

DEFAULT_GATEWAYS ¶

Gateways auto-enabled when wallet: is set and no explicit enable or gateways= calls were made. Both work zero-config with a BRC-100 wallet and expose non-overlapping proof headers.

DEFAULT_NETWORK ¶

Not documented.

DEFAULT_STATUS_ENDPOINT_PATH ¶

Not documented.

GATEWAY_METHODS ¶

Not documented.

GATEWAY_REGISTRY ¶

Not documented.

PAY_GATEWAY_KNOWN_OPTS ¶

Not documented.

PROOF_GATEWAY_KNOWN_OPTS ¶

Not documented.

VALID_NETWORKS ¶

Not documented.

VERIFY_ON_CHAIN_FALSY ¶

ENV values that disable on-chain verification. Anything else (including unset) leaves the safe default of true. Whitespace is trimmed, comparison is case-insensitive.

Attributes¶

arc_api_key [RW] ¶

Returns the value of attribute arc_api_key.

arc_client [RW] ¶

Returns the value of attribute arc_client.

arc_url [RW] ¶

Returns the value of attribute arc_url.

domain [RW] ¶

Returns the value of attribute domain.

exchange_rate_provider [RW] ¶

Returns the value of attribute exchange_rate_provider.

gateway_specs [R] ¶

Returns the value of attribute gateway_specs.

gateways [RW] ¶

Returns the value of attribute gateways.

logger [RW] ¶

Returns the value of attribute logger.

network [RW] ¶

Returns the value of attribute network.

operator_wallet_url [RW] ¶

Returns the value of attribute operator_wallet_url.

payee_locking_script_hex [RW] ¶

Returns the value of attribute payee_locking_script_hex.

routes [R] ¶

Returns the value of attribute routes.

server_wif [RW] ¶

Returns the value of attribute server_wif.

status_endpoint_path [RW] ¶

Returns the value of attribute status_endpoint_path.

status_endpoint_token [RW] ¶

Returns the value of attribute status_endpoint_token.

verify_on_chain [RW] ¶

Returns the value of attribute verify_on_chain.

wallet [RW] ¶

Returns the value of attribute wallet.

Public Instance Methods¶

enable(name, **options) ¶

Record a gateway to be constructed later during validate!. - @param name [Symbol] registered gateway name (e.g. +:pay_gateway+) - @param options [Hash] options forwarded to the gateway constructor - @raise [ConfigurationError] if the gateway name is not registered

enable_status_endpoint() ¶

Opt in to the read-only status endpoint at status_endpoint_path (default /_x402/status). Disabled by default.

The endpoint is always bearer-token authenticated. If status_endpoint_token is unset at validate! time, a random token is generated and logged once at startup so it can be copied into a curl command. Production deployments should set status_endpoint_token explicitly (typically from an environment variable) to suppress auto-generation. - @return [void]

find_route(request_method, request_path) ¶

Find the matching route for a request method and path. - @return [Route, nil]

initialize() ¶

• @return [Configuration] a new instance of Configuration

protect(method:, path:, amount_sats: = nil, amount_usd: = nil, arc_wait_for: = nil) ¶

Register a protected route. - @param method [String] HTTP method or "" for any - @param path [String, Regexp] exact path or pattern - @param amount_sats [Integer, #call] required payment in satoshis. Accepts a static Integer or a callable (Proc/Lambda) that returns the current sats amount at challenge time. Use a callable for fiat-denominated pricing with live exchange rates. - @param amount_usd [Numeric, nil] convenience — price in USD, resolved to sats at challenge time via +exchange_rate_provider+. Mutually exclusive with +amount_sats+. - @param* arc_wait_for [String, Symbol, nil] per-route ARC settlement override. +nil+ (default) uses the gateway's +arc_wait_for+ setting. A string value (e.g. +"SEEN_ON_NETWORK"+, +"MINED"+) overrides the gateway default for synchronous broadcast. +:async+ validates the transaction locally then enqueues it for background settlement via the gateway's +settlement_worker+, returning 200 immediately without waiting for ARC confirmation.

shared_arc_client() ¶

Returns a memoised ARC client instance. If arc_client has been injected directly, that takes precedence. Otherwise, builds one from arc_url (and optional arc_api_key), falling back to ARC.default when no explicit URL is configured. - @return [BSV::Network::ARC]

shared_wallet() ¶

Returns the shared wallet used by all gateways for key derivation (BRC-42/43) and, where supported, payment internalisation.

Resolution order: 1. An explicitly-set +@wallet+ (any BRC-100 compatible wallet, typically a +BSV::Wallet::WalletClient+), or a +RemoteWallet+ auto-constructed from +operator_wallet_url+ 2. A +ProtoWallet+ built from +server_wif+ (backwards compat) 3. +nil+ if neither is set - @return [BSV::Wallet::ProtoWallet, BSV::Wallet::WalletClient, RemoteWallet, nil]

status_endpoint_enabled?() ¶

• @return [Boolean] whether the status endpoint should be served

validate!() ¶

Validate the configuration and construct gateways from specs.

Called automatically at the end of X402.configure. Builds gateways from enable specs, validates all constraints, and emits operational warnings for development defaults. - @raise [ConfigurationError] if required fields are missing or invalid