Catalogo

Il catalogo elenca tutto ciò che è possibile acquistare: prodotti, paesi, periodi, prezzi unitari, le condizioni attuali e i parametri di protocollo. Non è richiesta alcuna autorizzazione.

I prezzi riportati nel catalogo sono indicativi. Il prezzo vincolante è esclusivamente l’importo indicato nel 402 Risposta relativa al tuo ordine specifico.

GEThttps://proxy-seller.com/api/x402/v1/catalog

Parametri di query

Nome	Tipo	Descrizione
prodotto	Stringa	Facoltativo. Restituire solo questo prodotto, ad esempio `?product=IPv4`. Prodotto sconosciuto o non pubblicato — `400`

Caching

Il catalogo viene aggiornato ogni 5 minuti. La risposta contiene Cache-Control: public, max-age=300 e ETag: "<catalog_version>"; invia If-None-Match con questo valore per ottenere 304 Not Modified. Con ?product=P l'ETag è "<catalog_version>:P".

Risposta

Nome	Tipo	Descrizione
generated_at	Stringa	Quando è stato creato il catalogo
catalog_version	Stringa	Modifiche solo in caso di variazioni del contenuto
valuta	Oggetto	`{asset, network, decimals}` dell'asset di pagamento
termini	Oggetto	`offer_version`, `offer_url`, `privacy_version`, `privacy_url`, `aup_summary`, `on_expiry`, `refund_policy`. Le versioni sono riportate in `accept_terms` di un nuovo ordine
uso_previsto	Oggetto	`{required: true, allowed: [{value, label}]}` — scopi di utilizzo consentiti
prodotti	Array	Blocchi di prodotto, vedi sotto
product_guide	Oggetto	Una breve descrizione di ogni prodotto e `recommendation_by_use` — prodotti consigliati per ogni scopo
protocollo	Oggetto	`x402_versions`, `schemes`, `networks`, `extensions`, `quote_ttl_seconds`, `max_timeout_seconds`, `poll`, `rate_limits`, e `sandbox_url` se disponibili

Vengono pubblicati solo i prodotti attualmente disponibili per l’acquisto. Un prodotto che non è presente nel catalogo non può essere ordinato.

Blocchi di prodotto

Nome	Tipo	Descrizione
prodotto	Stringa	`IPv4`, `ISP` oppure `IPv6`
display_name, description	Stringa	Nome e descrizione comprensibili all’utente
attributi	Oggetto	`dedicated`, `rotating`, `ip_version`, `asn_type` (`datacenter` oppure `isp`), `protocols`, `auth_methods`, `min_quantity`
adatto_a	Array	Scopi consigliati
paesi	Array	`[{country, periods: [{days, unit_price_usd, unit_price_atomic}]}]` — prezzo di un indirizzo per il periodo alla quantità minima
opzioni	Array	Sempre vuoto

Lo stesso blocco per IPv4_UPTIME e ISP_UPTIME, con display_name che termina con 100% uptime e attributes.uptime: true, attributes.gateways: true, auth_methods: ["userpass"]. Sono elencati solo i paesi e i periodi in cui è disponibile un uptime del 100%.

Nome	Tipo	Descrizione
prodotto	Stringa	`RESIDENT`
attributi	Oggetto	`rotating`, `asn_type: residential`, `protocols`, `auth_methods: ["userpass"]`, `geo_selection: per_request_login_suffix`, `unused_traffic: expires`, `one_package_per_account: true`, `topup_resets_period: true`
traffic_tiers	Array	`[{gb, period_days, price_usd, price_atomic}]` — pacchetti di traffico acquistabili
connessione	Oggetto	Host, porte, protocolli e sintassi del suffisso di accesso per il geo-targeting e le sessioni (senza credenziali)
locations_url	Stringa	Dove cercare informazioni su regioni, città e ISP, quando disponibili

Nome	Tipo	Descrizione
prodotto	Stringa	`MOBILE`
attributi	Oggetto	Inoltre `max_quantity_per_line`, `shared_host: true`, `volume_discounts: false`
opzioni	Array	Descrizioni delle opzioni di linea: `operator` e `rotation_min` (obbligatorio), `service_type` (impostazione predefinita `dedicated`)
paesi	Array	`[{country, operators: [{operator, name, traffic, service_types: [{service_type, rotations: [{rotation_min, ip_change, periods: [{days, unit_price_usd, unit_price_atomic}]}]}]}]}]` — solo le combinazioni in offerta. `ip_change`: `timer` oppure `link`

Nome	Tipo	Descrizione
prodotto	Stringa	`MIX` (indirizzi IPv4) oppure `MIX_ISP` (Indirizzi ISP)
distribuzione	Stringa	Come vengono suddivisi gli indirizzi tra i paesi di un pacco
pacchetti	Array	`[{mix, name, group: {id, name}, countries: [{country, share_pct}], sizes, periods: [{days, totals_usd}]}]`. `totals_usd` segue `sizes`; `null` significa che non è previsto alcun prezzo per questa taglia e questo periodo

Esempio

https://proxy-seller.com/api/x402/v1/catalog?product=IPv4

{
    "generated_at": "2026-11-02T10:00:44Z",
    "catalog_version": "df92823171697caa9dc15a42",
    "currency": {
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "network": "eip155:8453",
        "decimals": 6
    },
    "terms": {
        "offer_version": "2026-07-01",
        "offer_url": "https://proxy-seller.com/terms-of-service",
        "privacy_version": "2026-07-01",
        "privacy_url": "https://proxy-seller.com/privacy-policy",
        "aup_summary": ["no CSAM", "no DDoS", "no spam", "no credential stuffing"],
        "on_expiry": "access is disabled on the expiry date, no grace period",
        "refund_policy": "no refund on AUP suspension"
    },
    "intended_use": {
        "required": true,
        "allowed": [
            { "value": "web-scraping", "label": "Web scraping / data collection" },
            { "value": "price-monitoring", "label": "Price and marketplace monitoring" },
            { "value": "seo-monitoring", "label": "SERP and SEO monitoring" },
            { "value": "ads-verification", "label": "Ad verification" }
        ]
    },
    "products": [
        {
            "product": "IPv4",
            "display_name": "Dedicated IPv4",
            "description": "Dedicated datacenter IPv4 address, not shared.",
            "attributes": {
                "dedicated": true,
                "rotating": false,
                "ip_version": 4,
                "asn_type": "datacenter",
                "protocols": ["http", "https", "socks5"],
                "auth_methods": ["userpass", "ip"],
                "min_quantity": 1
            },
            "suitable_for": ["web-scraping", "price-monitoring", "seo-monitoring"],
            "countries": [
                {
                    "country": "US",
                    "periods": [
                        { "days": 7, "unit_price_usd": "0.90", "unit_price_atomic": "900000" },
                        { "days": 30, "unit_price_usd": "1.80", "unit_price_atomic": "1800000" },
                        { "days": 60, "unit_price_usd": "3.49", "unit_price_atomic": "3490000" }
                    ]
                }
            ],
            "options": []
        }
    ],
    "product_guide": {
        "IPv4": "Cheapest dedicated option with the highest throughput, easiest to detect. Best for tolerant targets.",
        "recommendation_by_use": { "web-scraping": ["ISP", "MIX_ISP", "IPv4", "MIX", "RESIDENT", "MOBILE"] }
    },
    "protocol": {
        "x402_versions": [2],
        "schemes": ["exact"],
        "networks": [
            {
                "network": "eip155:8453",
                "assets": ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
                "asset_transfer_methods": ["eip3009"],
                "payment_flow": "upfront"
            }
        ],
        "extensions": ["bazaar"],
        "quote_ttl_seconds": 900,
        "max_timeout_seconds": 900,
        "poll": { "default_interval_seconds": 10, "max_wait_seconds": 1800 },
        "rate_limits": { "unpaid_orders_per_min": 30 }
    }
}

Prodotto sconosciuto

{
    "error": "invalid_request",
    "message": "Request is invalid",
    "retryable": false,
    "retry_action": "abandon",
    "detail": "/product: unknown product, see /catalog"
}

Il catalogo viene creato subito dopo un riavvio. Riprovare dopo Retry-After secondi.

Note

I prezzi unitari sono calcolati sulla quantità minima di un prodotto. Gli sconti sul volume non sono indicati nel catalogo; vengono applicati nel 402 prezzo.
Il catalogo non contiene informazioni sulle disponibilità. Se gli indirizzi si esauriscono, ciò viene reso noto solo dopo il pagamento; vedi Ricevi l'ordine.