Guides

Quickstart

Five minutes from API key to a real payment in sandbox. We'll provision an agent, open a wallet, fund it with test money, send a payment, and verify the webhook.

Prerequisites

  • ─An AgentRail sandbox account. Request access at /signup.
  • ─Python 3.10+ or Node 20+.
  • ─An AGENTRAIL_KEY environment variable with your sandbox key.
Note
Sandbox keys begin with ar_test_…. Production keys begin with ar_live_…. Never check either into source control.

1 — Install the SDK

bash
# Python
pip install agentrail

# TypeScript
npm install @agentrail/sdk

2 — Create an agent

Every entity that moves money on AgentRail is an agent. You provision it once with the capabilities it needs and the limits it should respect.

step_2_agent.pyPython
from agentrail import AsyncClient

client = AsyncClient()  # reads AGENTRAIL_KEY from env

agent = await client.agents.create(
    name="dispatch-bot",
    description="Carrier-payment agent for fleet ops",
    capabilities=["payments.create", "wallets.read"],
    limits={"per_transaction": 25_000_00, "daily": 250_000_00},
)
print(agent.id)

3 — Open a wallet

The wallet is the account behind the agent. It holds balance, enforces the policy you set, and emits the events you'll subscribe to.

step_3_wallet.pyPython
wallet = await client.wallets.create(agent_id=agent.id)
print(wallet.id, wallet.balance.available)

4 — Fund the sandbox

Sandbox wallets start at zero. Add test funds with the helper below — it settles instantly.

step_4_fund.pyPython
await client.sandbox.wallets.credit(
    wallet_id=wallet.id,
    amount=100_000_00,  # $100,000.00
)

5 — Send a payout

Payouts is a single call. AgentRail handles rail selection, policy enforcement, and screening before the funds move.

step_5_pay.pyPython
payment = await client.payments.create(
    wallet_id=wallet.id,
    recipient="acme-logistics",  # any AgentRail counterparty
    amount=4250_00,
    memo="Run 2026-05-19",
    idempotency_key="run-2026-05-19",
)
print(payment.id, payment.status, payment.rail)
Heads up
Always pass an idempotency_keyin production. A network blip or a retried agent call won't double-send the payment.

6 — Verify webhook

Webhook payloads are signed. Verify the signature before trusting the body — full schema and example code is inWebhooks.

webhook.pyPython
from agentrail import verify_webhook

@app.post("/agentrail/webhook")
async def handle(req):
    body = await req.body()
    sig  = req.headers["agentrail-signature"]
    event = verify_webhook(body, sig, secret=os.environ["WEBHOOK_SECRET"])
    # event.type, event.data, event.created_at
    return {"ok": True}

Next

← Back to docs indexAsk AgentRail Chat →