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. To pay programmatically, settle the amount from e.accepts out-of-band and retry the call with the resulting X-PAYMENT header via Client(extra_headers={"X-PAYMENT": "..."}). Automatic in-client on-chain settlement is planned for a future release; the current version surfaces the requirements so you stay 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/AgentMarginRouter

License

MIT © NovaNest