AEGIS SDK

Developer Docs

Privacy-routed HTTP requests for AI agents and developers. One function call routes any request through a residential exit node and bills USDC from your balance.

Installation

The Chrome extension is the primary way to use AEGIS. For API / agent use, generate a key on the Agent SDK page and call the REST API directly — no SDK install required.

Chrome extension

1. Download the extension package from github.com/sorrowzzz/AegisPrivacy/releases
2. Open chrome://extensions  →  enable "Developer mode"
3. Click "Load unpacked"  →  select the extracted folder
4. Pin AEGIS to your toolbar and connect your Solana wallet

REST API (no install)

curl -X POST https://aegisprivacy.org/api/x402/request \
  -H "Authorization: Bearer aegis_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://httpbin.org/ip","country":"US","ip_class":"datacenter"}'

Native SDK packages (npm / pip) are in development.

Quick start

Get your API key from the Agent SDK page, then make your first proxied request. Available countries: US, CA, AU.

cURL

# Route a request through a US datacenter exit node
curl -X POST https://aegisprivacy.org/api/x402/request \
  -H "Authorization: Bearer aegis_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://httpbin.org/ip","country":"US","ip_class":"datacenter"}'

# Route through Canada
curl -X POST https://aegisprivacy.org/api/x402/request \
  -H "Authorization: Bearer aegis_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://httpbin.org/ip","country":"CA","ip_class":"datacenter"}'

Response

{
  "ok": true,
  "body": "{"origin": "137.184.216.6"}",
  "contentType": "application/json"
}

API reference

new Aegis(options)

apiKeystringrequired — Your AEGIS API key

baseUrlstringoptional — Override API endpoint (for testing)

defaultCountrystringoptional — Default exit country. Default: "US"

defaultIpClassstringoptional — Default IP class. Default: "residential"

aegis.fetch(url, options?)

Full-control request. All options are optional.

urlstringTarget URL to fetch through AEGIS

methodstringHTTP method. Default: "GET"

countrystringExit country code. Default: constructor default

ipClassstring"residential" | "datacenter" | "mobile"

headersobjectExtra headers sent to the target

bodystring | objectRequest body. Objects are JSON-encoded

aegis.balance()

Returns your remaining USDC balance.

const { usdc } = await aegis.balance()
console.log(`$${usdc} remaining`)

Error handling

All errors extend AegisError with a status and code field.

import { Aegis, AegisBalanceError, AegisNodeError } from '@aegis/sdk'

try {
  const res = await aegis.get('https://example.com')
} catch (err) {
  if (err instanceof AegisBalanceError) {
    console.log('Out of funds — top up at aegisprivacy.org/dashboard')
  } else if (err instanceof AegisNodeError) {
    console.log('No nodes in that country right now')
  } else {
    throw err
  }
}

AegisAuthError401Invalid or missing API key

AegisBalanceError402Insufficient USDC balance

AegisNodeError503No nodes available in requested country

AegisErrorvariesBase class for all AEGIS errors

Supported countries

Pass the 2-letter ISO code to country. The following countries have active nodes.

🇺🇸 United States

🇨🇦 Canada

🇦🇺 Australia

More countries come online as operators register nodes. See Operators to add your own node.

Pricing

Requests are billed from your AEGIS balance. No monthly fees.

Base request$0.001 USDC

Residential exit+$0.0005 USDC

Datacenter exitincluded

Bandwidth$0.005 USDC / MB

Rate limit60 requests / min

Minimum top-up$1.00 USDC

Top up your balance at aegisprivacy.org/dashboard.