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).
• 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/*