Configuration Reference

This page covers programmatic configuration via the Rust and Python SDKs. All configuration objects provide both Rust functions and Python bindings.

AppState

The shared application state accessible by every request handler. Holds the database connection, payment configuration, server URL, bind address, and dashboards state.

AppState::new takes a DashboardsState. Pass an empty one if you don’t want dashboards — the API endpoints work the same either way.

Construction

#![allow(unused)]
fn main() {
// Rust
use std::path::PathBuf;
use tiders_x402_server::dashboard::DashboardsState;

let dashboards_state = DashboardsState {
    root: PathBuf::new(),
    dashboards: vec![],
};

let state = AppState::new(
    db,
    payment_config,
    Url::parse("https://api.tiders.com").unwrap(),
    "0.0.0.0:4021".to_string(),
    dashboards_state,
);
}

# Python — dashboards configuration via SDK is not yet exposed; use the CLI for that.
state = AppState(database, payment_config, "https://api.tiders.com", "0.0.0.0:4021")

FacilitatorClient

HTTP client for communicating with a remote x402 facilitator. Wraps a base URL and derives /verify, /settle, and /supported endpoints automatically.

Construction

#![allow(unused)]
fn main() {
// Rust
let facilitator = FacilitatorClient::try_from("https://facilitator.x402.rs")
    .expect("Failed to create facilitator client");
}

# Python
facilitator = FacilitatorClient("https://facilitator.x402.rs")

Getters

Setters

GlobalPaymentConfig

Central payment configuration shared across all request handlers. Holds the facilitator client, response format, timeout, and per-table pricing rules.

Construction

All fields except facilitator are optional and fall back to sensible defaults.

#![allow(unused)]
fn main() {
// Rust - with defaults
let config = GlobalPaymentConfig::default(facilitator);

// Rust - with custom values
let config = GlobalPaymentConfig::new(
    facilitator,
    Some("text/csv".to_string()),       // mime_type
    Some(600),                           // max_timeout_seconds
    Some("Custom description".to_string()), // default_description
    None,                                // offers_tables (defaults to empty)
);
}

# Python - with defaults
config = GlobalPaymentConfig(facilitator)

# Python - with custom values
config = GlobalPaymentConfig(
    facilitator,
    mime_type="text/csv",
    max_timeout_seconds=600,
    default_description="Custom description",
)

Getters

Setters

PriceTag

A single pricing tier for a table. Defines who gets paid, how much, and in which token. A table can have multiple price tags for tiered pricing. The pricing model (per-row, fixed, or metadata price) is specified via the pricing field.

PricingModel

Construction (Per-Row)

#![allow(unused)]
fn main() {
// Rust
let price_tag = PriceTag {
    pay_to: ChecksummedAddress::from_str("0x...").unwrap(),
    pricing: PricingModel::PerRow {
        amount_per_item: TokenAmount(usdc.parse("0.002").unwrap().amount),
        min_total_amount: None,
        min_items: None,
        max_items: None,
    },
    token: usdc.clone(),
    description: None,
    is_default: true,
};
}

# Python — per-row pricing (constructor)
# amount_per_item accepts a string ("0.002") or int (2000) for smallest token units
price_tag = PriceTag(
    pay_to="0x...",
    amount_per_item="0.002",
    token=usdc,
    is_default=True,
)

Construction (Fixed)

#![allow(unused)]
fn main() {
// Rust
let price_tag = PriceTag {
    pay_to: ChecksummedAddress::from_str("0x...").unwrap(),
    pricing: PricingModel::Fixed {
        amount: TokenAmount(usdc.parse("1.00").unwrap().amount),
    },
    token: usdc.clone(),
    description: Some("Fixed price query".to_string()),
    is_default: true,
};
}

# Python — fixed pricing (static method)
price_tag = PriceTag.fixed(
    pay_to="0x...",
    fixed_amount="1.00",
    token=usdc,
    description="Fixed price query",
    is_default=True,
)

Construction (Metadata Price)

#![allow(unused)]
fn main() {
// Rust
let price_tag = PriceTag {
    pay_to: ChecksummedAddress::from_str("0x...").unwrap(),
    pricing: PricingModel::MetadataPrice {
        amount: TokenAmount(usdc.parse("1.00").unwrap().amount),
    },
    token: usdc.clone(),
    description: Some("Metadata access fee".to_string()),
    is_default: false,
};
}

# Python — metadata pricing (static method)
price_tag = PriceTag.metadata_price(
    pay_to="0x...",
    amount="1.00",
    token=usdc,
    description="Metadata access fee",
)

PriceTag is immutable after creation – create a new one to change values.

TablePaymentOffers

Groups the payment configuration for a single table: its pricing tiers, whether payment is required, and metadata shown to clients.

Construction

#![allow(unused)]
fn main() {
// Rust - paid table
let offer = TablePaymentOffers::new("my_table".to_string(), vec![price_tag], Some(schema))
    .with_description("My dataset".to_string());

// Rust - free table
let free = TablePaymentOffers::new_free_table("public_table".to_string(), Some(schema));
}

# Python - paid table (description can be set at creation)
offer = TablePaymentOffers("my_table", [price_tag], schema=schema, description="My dataset")

# Python - free table
free = TablePaymentOffers.new_free_table("public_table", schema=schema, description="Public data")

Getters

Setters / Mutators

Tiered Pricing Example

Charge less per row for larger queries (per-row pricing):

#![allow(unused)]
fn main() {
// Default: $0.002/row for any query
let default_tier = PriceTag {...}

// Bulk: $0.001/row for queries returning 100+ rows
let bulk_tier = PriceTag {...}

let offer = TablePaymentOffers::new("my_table".to_string(), vec![default_tier], Some(schema))
    .add_payment_offer(bulk_tier);
}

The client receives both options in the 402 response and can choose the cheaper one.

Supported Networks

Currently supported USDC deployments: