neura-agent — the agent client for NEURA Compute (Python)

OpenAI-compatible inference where the agent pays for itself.

1. Automatic HTTP 402 handling — when NEURA says payment required it answers with an x402 envelope. The client settles it from the agent's own wallet on Base (USDC, 1 credit = $1), submits the tx hash, waits for the credit, and retries. No human, no card.
2. Wallet-only onboarding (SIWE / EIP-4361) — an agent holding only a wallet key creates its account and self-provisions an API key. If the very first request is anonymous, the client does this itself before paying.

pip install neura-agent

With the official OpenAI SDK

import os
from openai import OpenAI
from neura_agent import NeuraAgent

neura = NeuraAgent(
    wallet_key=os.environ["AGENT_WALLET_KEY"],  # a hot wallet holding a little USDC on Base
    auto_fund=True,                             # 402 -> (login) -> pay USDC -> credited -> retry
    max_usdc_per_fund=5,                        # hard cap per payment
)

client = OpenAI(
    base_url=neura.base_url + "/v1",
    api_key="wallet",                 # placeholder — the client injects the key it provisions
    http_client=neura.http_client(),  # 402s handled transparently
)

r = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    messages=[{"role": "user", "content": "Hello!"}],
)

Already have an API key? Pass api_key= and the wallet is only used to pay.

With LangChain

from langchain_openai import ChatOpenAI
from neura_agent import NeuraAgent

neura = NeuraAgent(wallet_key=os.environ["AGENT_WALLET_KEY"], auto_fund=True)
llm = ChatOpenAI(
    model="openai/gpt-oss-120b",
    base_url=neura.base_url + "/v1",
    api_key="wallet",
    http_client=neura.http_client(),
)
print(llm.invoke("Who pays for this call?").content)

With CrewAI

CrewAI routes through LiteLLM, which does not take a custom http client, so pre-fund before the crew runs and give it the provisioned key:

from crewai import LLM
from neura_agent import NeuraAgent

neura = NeuraAgent(wallet_key=os.environ["AGENT_WALLET_KEY"], auto_fund=True)
neura.login_with_wallet()
if neura.credit_balance() < 2:
    neura.fund(neura.discovery(), credits=2)   # 2 USDC -> 2 credits

llm = LLM(model="openai/openai/gpt-oss-120b", base_url=neura.base_url + "/v1", api_key=neura.api_key)

See examples/ for runnable versions of all three.

What the platform sends, and what the client does with it

A 402 carries an x402 v1 envelope. Production today:

{
  "code": "PAYMENT_REQUIRED",
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact", "network": "base",
    "maxAmountRequired": "1000000",
    "payTo": "0x404f4E91Fc8Bf0c5fcfC71b4C06E2c0faACdb2c5",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "extra": { "settlement": "transfer", "assetSymbol": "USDC", "decimals": 6,
               "creditEndpoint": "/api/depin/credits/topup-usdc" }
  }],
  "authenticate": { "scheme": "EIP-4361", "nonce": "/api/auth/wallet/nonce", "verify": "/api/auth/wallet" }
}

choose_offer(body) picks the rail: the USDC exact offer whenever present; a neura-burn offer only when advertised with a live rate. If the platform offers nothing the client can settle, it raises instead of guessing.

Safety model

• Nothing moves on-chain unless you pass wallet_key and auto_fund=True (or call fund() yourself).
• A returning wallet pays nothing to resume: after the SIWE login the client retries with the tenant's key first, and funds only if the platform still answers 402 for that tenant. Restarting an agent never buys credits it has.
• max_usdc_per_fund (default 5) caps any single payment; max_neura_per_burn (default 100) caps any burn.
• pin_pay_to refuses to send USDC to any receiver other than the one you pin.
• On 402 without auto-funding, PaymentRequiredError carries remediation, x402 and the full body so your own logic can decide.
• Use a dedicated hot wallet with a small balance — never a treasury key.

Allowances: the owner's leash, honoured by the client

The platform's owner-set allowances answer with 403/429 and a code. The client reads them before it ever thinks about paying:

• AGENT_PAUSED (the owner's kill switch) raises AgentPausedError. The client never funds, never retries: only the owner can resume the key.
• ALLOWANCE_DAILY, ALLOWANCE_MONTHLY, OUTSIDE_ALLOWED_HOURS, SELF_LIMIT_EXCEEDED are retryable and come with Retry-After. By default the client raises AllowanceError with retry_after_seconds so your loop can decide. Set max_retry_after_seconds and, when the wait fits, the client sleeps exactly that long and retries once.
• MODEL_NOT_ALLOWED, ALLOWANCE_PER_CALL are not retryable and raise AllowanceError with retryable=False even when waiting is allowed.
• Any other 403/429 passes through untouched.

The agent's own key can only tighten its allowance (PUT /api/agent/allowance). A wallet tenant has no console, so its owner acts by signature: agent.owner_allowance(api_key_id, allowance={...}), action="kill" or action="resume" signs a fresh SIWE message with wallet_key and posts it to /api/agent/allowance/owner. Run that where the wallet lives, not inside the agent: whoever can sign can loosen the leash.

API

Develop / publish

cd packages/neura-agent-py
pip install -e ".[test]"
pytest
python -m build && twine upload dist/*