Allium Blockchain Data (x402)

Your job: Get on-chain data without fumbling. Pay per call with USDC — no API key, no registration.

Pick the Right Skill

Read the user's request, then fetch the matching skill before proceeding.

If unsure, fetch developer for realtime questions or explorer for analytical questions.

Fallback: If the docs browse endpoint doesn't return what you need, fetch https://docs.allium.so/llms.txt for a complete documentation index.

Common Tokens

Chain names are lowercase: ethereum, base, solana, arbitrum, polygon, hyperevm.

Supported Chains (call once per session)

Call before any /developer/ endpoint. Cache the result. Skip for /docs/ and /explorer/.

curl "https://agents.allium.so/api/v1/supported-chains/realtime-apis/simple"

Returns { "/api/v1/developer/prices": ["ethereum", "solana", ...], ... } — validate chain before calling.

Payment Client (x402)

Every paid endpoint returns 402 on first call. This client handles the payment automatically.

# /// script
# requires-python = ">=3.10"
# dependencies = ["privy-client", "httpx"]
# ///
import base64, json, os, pathlib, secrets, httpx
from privy import PrivyAPI

def load_credentials():
    creds = pathlib.Path.home() / ".config" / "allium" / "credentials"
    if creds.exists():
        for line in creds.read_text().splitlines():
            line = line.strip()
            if line and not line.startswith("#") and "=" in line:
                k, v = line.split("=", 1)
                os.environ.setdefault(k.strip(), v.strip())

load_credentials()

BASE_URL = "https://agents.allium.so"
TARGET_NETWORK = os.environ["ALM_TARGET_NETWORK"]

privy = PrivyAPI(app_id=os.environ["PRIVY_APP_ID"], app_secret=os.environ["PRIVY_APP_SECRET"])
WALLET_ID = os.environ["PRIVY_WALLET_ID"]
WALLET_ADDRESS = privy.wallets.get(wallet_id=WALLET_ID).address

def x402_request(http, method, url, **kwargs):
    headers = kwargs.pop("headers", {})
    r = http.request(method, url, headers=headers, **kwargs)
    if r.status_code != 402:
        return r
    details = r.json()
    option = next((a for a in details["accepts"] if a["network"] == TARGET_NETWORK), None)
    if not option:
        raise ValueError(f"No payment option for {TARGET_NETWORK}")
    chain_id = int(option["network"].split(":")[1])
    nonce = "0x" + secrets.token_hex(32)
    typed_data = {
        "types": {
            "EIP712Domain": [{"name":"name","type":"string"},{"name":"version","type":"string"},
                {"name":"chainId","type":"uint256"},{"name":"verifyingContract","type":"address"}],
            "TransferWithAuthorization": [{"name":"from","type":"address"},{"name":"to","type":"address"},
                {"name":"value","type":"uint256"},{"name":"validAfter","type":"uint256"},
                {"name":"validBefore","type":"uint256"},{"name":"nonce","type":"bytes32"}],
        },
        "domain": {"name": option["extra"]["name"], "version": option["extra"]["version"],
            "chainId": chain_id, "verifyingContract": option["asset"]},
        "primary_type": "TransferWithAuthorization",
        "message": {"from": WALLET_ADDRESS, "to": option["payTo"], "value": str(option["amount"]),
            "validAfter": "0", "validBefore": str(option["maxTimeoutSeconds"]), "nonce": nonce},
    }
    sig = privy.wallets.rpc(wallet_id=WALLET_ID, method="eth_signTypedData_v4",
        params={"typed_data": typed_data})

    resource = details.get("resource", {})

    payload = {
        "x402Version": details["x402Version"],
        "resource": {"url": resource.get("url", url), "description": resource.get("description", ""),
            "mimeType": resource.get("mimeType", "application/json")},
        "accepted": {"scheme": option["scheme"], "network": option["network"],
            "amount": str(option["amount"]), "asset": option["asset"], "payTo": option["payTo"],
            "maxTimeoutSeconds": option["maxTimeoutSeconds"], "extra": option.get("extra", {})},
        "payload": {"signature": sig.data.signature,
            "authorization": {"from": WALLET_ADDRESS, "to": option["payTo"],
                "value": str(option["amount"]), "validAfter": "0",
                "validBefore": str(option["maxTimeoutSeconds"]), "nonce": nonce}},
    }
    headers["PAYMENT-SIGNATURE"] = base64.b64encode(json.dumps(payload).encode()).decode()
    return http.request(method, url, headers=headers, **kwargs)

Errors

Best Practices

1. Cache supported chains — call once per session, not per request
2. Batch requests — use array format for multiple tokens in one call
3. Handle 429 — exponential backoff on rate limits
4. Validate chains — check against supported-chains before calling
5. Reuse connections — httpx.Client(timeout=60.0) context manager
6. Don't commit secrets — credentials live in ~/.config/allium/credentials