agent-margin-router

Agent Margin Router — Python SDK

Official Python client for the Agent Margin Router API — one pay-per-call HTTP interface that gives AI agents and applications clean, LLM-ready data across 39 endpoints: web scraping & search, crypto & market data, on-chain reads, DeFi analytics, and developer utilities.

• No signup to start — every wallet gets 3 free calls per endpoint family via the X-WALLET header.
• Pay per call — settle in USDC on Base through the x402 standard, or use an API key.
• Typed — one Python method per endpoint, full type hints, py.typed shipped.
• Small footprint — a single runtime dependency (httpx).

---

Installation

pip install agent-margin-router

Requires Python 3.9+.

---

Quickstart

from agent_margin_router import Client

# 3 free calls per wallet — no signup, no key.
client = Client(wallet="0xYourWalletAddress000000000000000000000000")

result = client.token_price(asset="ETH")
print(result["price"])        # median price across venues
print(result["cost_usdc"])    # 0 while on the free tier
print(result["routing"])      # provider, latency, cache hit, fallbacks

Using an API key instead (usage billed to the key's wallet):

client = Client(api_key="amr_live_...")
spread = client.market_spread(asset="ETH", buy_venue="binance", sell_venue="coinbase")

The client is a context manager and reuses one HTTP connection pool:

with Client(wallet="0x...") as client:
    fg = client.fear_greed()
    news = client.news_search(query="ethereum ETF", max_results=10)

---

Authentication

Pass one of the following to Client(...):

---

Paying for calls (x402)

Once the free tier is exhausted and no API key is supplied, the API responds with HTTP 402. The SDK raises PaymentRequiredError, which carries the exact payment requirements returned by the server (asset, network, amount, pay-to address, facilitator):

from agent_margin_router import Client, PaymentRequiredError

client = Client()  # anonymous
try:
    client.gas_fees(chain="base")
except PaymentRequiredError as e:
    print(e)                 # human-readable summary incl. price & pay-to
    print(e.accepts)         # list of accepted payment options (USDC on Base, ...)

Payments settle in USDC on Base to the router's fixed receiving address. You can either handle 402s yourself (settle the amount from e.accepts out-of-band and retry with an X-PAYMENT header via Client(extra_headers={"X-PAYMENT": "..."})), or let the SDK settle them automatically — see below.

---

Automatic payment (opt-in, since v0.2)

Give the client an AutoPay helper backed by your own wallet's private key and 402s are settled transparently: the SDK signs a single-use, exact-amount EIP-3009 TransferWithAuthorization (the scheme x402 facilitators expect) and retries the call with the X-PAYMENT header. Install the extra:

pip install "agent-margin-router[autopay]"

from agent_margin_router import Client, AutoPay

client = Client(auto_pay=AutoPay(
    private_key="0x...",     # the PAYING wallet's key — never leaves your process
    max_price_usd=0.10,      # hard per-call spend cap; pricier 402s are re-raised
))

data = client.token_price(asset="ETH")   # 402 is signed & settled automatically

The private key can also come from the AGENT_MARGIN_ROUTER_PRIVATE_KEY environment variable (AutoPay() with no argument). Key points:

• Your key, your control. The key belongs to the paying agent, is used only locally to sign the transfer authorization, and is never transmitted anywhere.
• Bounded. Each signature authorizes a gasless, single-use transfer of the exact amount to the address the server put in payTo — nothing more. A random 32-byte nonce plus the server-side replay cache prevent reuse.
• Capped. max_price_usd is a client-side ceiling; any 402 above it raises PaymentRequiredError instead of paying. Leave it unset only if you trust every endpoint you call.
• Token choice. prefer_symbol="USDC" (default) picks the stablecoin when several are accepted.
• Hardware/remote signers. Pass signer=<callable> plus account_address="0x..." to sign with a custom backend instead of a raw key.

Without auto_pay the behavior is unchanged from v0.1: a PaymentRequiredError is raised and you stay fully in control.

---

Error handling

All exceptions derive from AgentMarginRouterError:

from agent_margin_router import RateLimitError

try:
    client.web_search(query="...")
except RateLimitError as e:
    time.sleep(e.retry_after or 1.0)

---

Response shape

Every endpoint returns a dict. Most endpoints put their payload fields directly on the top level of the response, next to a common set of billing and routing metadata fields. For example, token_price() returns price, quote, sources, confidence, … right alongside cost_usdc and routing:

{
  // --- endpoint-specific fields (vary per endpoint) ---
  "asset": "ETH",
  "price": 3125.42,
  "quote": "USD",
  "sources": [ "..." ],
  "confidence": 0.99,

  // --- common metadata (present on every response) ---
  "cost_usdc": 0.01,
  "token": "USDC",            // or "FREE" while on the free tier
  "fetched_at": "2026-09-16T10:00:00Z",
  "freshness_seconds": 3,
  "routing": {
    "provider": "coinbase",
    "fallback_used": false,
    "providers_tried": ["binance", "coinbase"],
    "cache_hit": false,
    "latency_ms": 180
  }
}

A few endpoints (for example extract_clean()) instead nest their payload under a data key — inspect result.keys() if you are unsure. The common metadata fields (cost_usdc, token, fetched_at, freshness_seconds, routing) are always on the top level.

---

Endpoints

All 39 endpoints, one typed method each. Prices are per successful call; the first 3 calls per wallet are free.

currency_convert() uses from_ as the parameter name (since from is a reserved word in Python); it is sent to the API as from.

---

Links

• Website: https://agentmarginrouter.com
• API docs: https://agentmarginrouter.com/docs
• Live discovery catalog: https://agent-margin-router-production.up.railway.app/discovery/resources
• Source: https://github.com/AgentMarginRouter/agent-margin-router-python

License

MIT © NovaNest