Quickstart

A Marvel exit is an HTTP CONNECT proxy at resi.marvel.sh:9000. You authenticate with your API key as the proxy username and a target string as the proxy password. That’s the whole interface — anything that speaks HTTP proxy works unchanged.

1. Create an account and add balance. Sign up at marvel.sh, then buy a prepaid bundle from the dashboard. A key with a zero balance cannot proxy — the gateway returns 402 until you top up. See Pricing & bundles.

2. Create an API key. In the dashboard, open Keys and create one. It looks like mk_live_… and is shown once — store it now. You can revoke it anytime. See Authentication.

3. Make your first request. Use your key as the username and country-US (any ISO 3166-1 alpha-2 code) as the password.

   curl

   curl -x resi.marvel.sh:9000 \
     -U "mk_live_xxxxxxxxxxxxxxxx:country-US" \
     https://api.ipify.org?format=json
   # { "ip": "76.121.x.x" }  — a US residential address

   Python

   import requests
   
   proxy = "http://mk_live_xxxxxxxxxxxxxxxx:country-US@resi.marvel.sh:9000"
   r = requests.get(
       "https://api.ipify.org?format=json",
       proxies={"http": proxy, "https": proxy},
       timeout=30,
   )
   print(r.json())  # {'ip': '76.121.x.x'}

   Node

   import axios from 'axios';
   import { HttpsProxyAgent } from 'https-proxy-agent';
   
   const proxy = 'http://mk_live_xxxxxxxxxxxxxxxx:country-US@resi.marvel.sh:9000';
   const agent = new HttpsProxyAgent(proxy);
   
   const { data } = await axios.get('https://api.ipify.org?format=json', {
     httpAgent: agent,
     httpsAgent: agent,
   });
   console.log(data); // { ip: '76.121.x.x' }

   Browser / scraper

   Most tools take a host:port:user:pass string:

   resi.marvel.sh:9000:mk_live_…:country-US

   In Playwright or Puppeteer:

   const browser = await chromium.launch({
     proxy: {
       server: 'http://resi.marvel.sh:9000',
       username: 'mk_live_xxxxxxxxxxxxxxxx',
       password: 'country-US',
     },
   });

4. Inspect the verdict (optional). The exit behind your request already cleared the Gauntlet. To see its evidence — Purity, Grade, and Seals — issue a node through the control API:

   curl -X POST https://api.marvel.sh/v1/nodes \
     -H "Authorization: Bearer $MARVEL_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"country":"US"}'

Sticky or rotating

No session token means a fresh exit per request (rotating). Add -session-<id> to the password to pin the same exit for the session’s lifetime — see Targeting.

What just happened

• Your key resolved to your account (407 if it’s unknown or revoked).
• country-US was parsed into a target. ASN/ISP tokens are rejected — targeting is country-only.
• The gateway pinned a live, vetted exit from the US Reserve and tunnelled your request through it. You’re billed only for the bytes that flowed.

Next

• Authentication — accounts, sessions, and key lifecycle.
• Targeting — sticky sessions and a per-request purity floor.
• API reference — every /v1 endpoint.