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

Install the SDK for your language:

TypeScript / Node.js

npm install @aegis/sdk

Python

pip install aegis-sdk

Quick start

Get your API key from the Agent SDK page, then make your first proxied request:

TypeScript

import { Aegis } from '@aegis/sdk'

const aegis = new Aegis({ apiKey: 'aegis_your_key_here' })

// GET request through a US residential exit node
const res = await aegis.get('https://httpbin.org/ip')
console.log(await res.json())
// { "origin": "12.34.56.78" }  ← a residential US IP, not yours

// POST request through a Japanese exit node
const res2 = await aegis.post(
  'https://api.example.com/data',
  { query: 'hello' },
  { country: 'JP' }
)
const data = await res2.json()

Python

from aegis import Aegis

aegis = Aegis(api_key="aegis_your_key_here")

# GET request through a US residential exit node
res = aegis.get("https://httpbin.org/ip")
print(res.json())
# { "origin": "12.34.56.78" }  ← a residential US IP, not yours

# POST through a Japanese exit node
res2 = aegis.post(
    "https://api.example.com/data",
    {"query": "hello"},
    country="JP",
)

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. Node availability varies.

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.