← all AgentPay tools

session_create

Open a budget-capped agent session on AgentPay. Pay $0.01 USDC once — get a session_id, budget config, and gateway URL. Enforces a hard max_spend cap across all subsequent tool calls via the AgentPay SDK. The entry point for agents discovering AgentPay on Base Bazaar..

When agents use this

You want to start an AgentPay session with a hard spend cap and get a session_id for tracking.

Parameters

name	type	required	description
label	string	no	Optional human-readable label for this session
max_spend	string	no	Hard budget cap in USDC for this session, e.g. '0.10'
agent_address	string	no	Your wallet address (Stellar G... or EVM 0x...)

Returns

session_id, max_spend, agent_address, gateway_url, tools_endpoint, created_at, receipt (tx_hash + network)

Example response

{
  "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "max_spend": "0.10",
  "agent_address": "GBCVQCNFWPM3GDO4GPT4YEQ42ZHPY67QTJA3WN5ERQIKQDXKBX62SLNJ",
  "label": null,
  "gateway_url": "https://agentpay.tools",
  "tools_endpoint": "https://agentpay.tools/tools",
  "created_at": "2026-05-27T12:00:00Z",
  "receipt": {
    "tx_hash": "0xabc...def",
    "network": "base",
    "amount_usdc": "0.01"
  },
  "sdk_hint": "Use `from agentpay import Session` to enforce the max_spend cap client-side."
}

Call it — HTTP (x402)

curl -X POST https://agentpay.tools/tools/session_create/call \
  -H 'Content-Type: application/json' \
  -d '{"parameters": {}, "agent_address": "<your wallet or any identifier>"}'
# → HTTP 402 challenge → pay USDC on Base (gasless EIP-3009) or Stellar,
#   retry with the payment proof header. The SDK below does this for you.

Call it — Python SDK

from agentpay import quickstart  # pip install agentpay-x402

s = quickstart(max_spend=0.10)   # hard budget cap; mints a wallet, no funding needed
r = s.call("session_create", {})
print(r.data)                    # + r.cost, r.tx, r.network — full receipt

Call it — MCP

npx -y @romudille/agentpay-mcp   # keyless; exposes session_create to any MCP agent runtime