Sessions & the Reserve

The Reserve

The Reserve is the live pool of exits that have cleared the Gauntlet. Every member carries a full verdict — Purity, Grade, and Seals — and is bucketed by country and grade. It is the single source the gateway selects from, so what the availability endpoint reports is exactly what a dial will get.

5

gates per node

S · A · B

grade buckets

live.

only countries we can serve now

How an exit is chosen

For a request targeting country-XX, the selector draws from that country’s live pool, best grade first — S Pristine before A Premium before B Standard. A min_purity floor narrows the candidates further. So a node is high-grade by default; you only ever tighten, never loosen.

Honest scarcity

Marvel only offers countries it can serve right now. If a country has no live capacity, the gateway returns 503 and the availability list omits it entirely — there are no phantom regions and no silent reroute to “somewhere close.”

Rotating vs sticky

The presence of a -session-<id> token is the only difference.

• Rotating (no session) — every request samples a fresh exit. Ideal for breadth: each request looks independent.
• Sticky (-session-<id>) — the pair (your account, session id) is bound to one exit, so repeat requests reuse the same address. Ideal for stateful flows: logins, carts, pagination.

A sticky exit is held for its lifetime; the authoritative expiry is the expires_at field returned by /v1/nodes (on the order of minutes). When a pinned exit expires or is dropped, the next request on that session is transparently re-pinned to a fresh, equally-vetted exit — you never have to handle a dead session.

# Pin a sticky exit and read back its verdict + expiry
curl -X POST https://api.marvel.sh/v1/nodes \
  -H "Authorization: Bearer $MARVEL_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"country":"US","session":"cart_19f3"}'
# { "session": "cart_19f3", "exit_ip": "76.121.x.x", "country": "US", "asn": 7018,
#   "purity": 99, "grade": "S", "seals": ["authentic","residential","clean"],
#   "expires_at": "…", "dial": "country-US-session-cart_19f3" }

# List your live sticky exits
curl https://api.marvel.sh/v1/nodes -H "Authorization: Bearer $MARVEL_TOKEN"

You never see the upstream

The dial string and your API key are the entire customer surface. The underlying supplier endpoint and its credentials live only inside the gateway — they are never returned, logged, or billable. If an exit fails mid-stream, the gateway re-draws internally; a dropped IP never carries your traffic.

Self-healing by construction

A dropped or dead exit is removed from the Reserve the moment it fails a re-check, and the GET /v1/nodes list drops it too. Combined with best-grade-first selection, the pool you draw from is always the currently clean one — not a snapshot from an hour ago.