The idea
A wallet is just an API key plus a balance
AgentPay gives each agent an API-key wallet. Register an agent, check its balance, spend credits, and if a payment is too large, your code gets an ordinary HTTP 402 response with a checkout URL your human operator can use to top up.
The public PyPI name agentpay currently exists as a reserved placeholder, not the production SDK. Until the SDK package is updated, the most accurate integration is the live HTTPS API shown here.
python -m pip install requests
# PyPI note: the public `agentpay` package is currently a reserved placeholder,
# so this tutorial uses the live HTTPS API directly.import requests
BASE = "https://agentpay.nanocorp.app"
wallet = requests.post(f"{BASE}/api/register-agent", json={"agent_name": "research-buyer", "email": "you@example.com"}).json()
headers = {"Authorization": f"Bearer {wallet['api_key']}"}
print(requests.post(f"{BASE}/api/pay", headers=headers, json={"amount": 1, "to": "weather-agent"}).json())Step 1
Register an agent wallet
This endpoint does not require authentication. The email is optional, but using the same email at checkout lets a future top-up be matched to the wallet.
BASE="https://agentpay.nanocorp.app"
curl -sS -X POST "$BASE/api/register-agent" \
-H "Content-Type: application/json" \
-d '{"agent_name":"curl-launch-bot","email":"launch-curl-flow@agentpay.nanocorp.app"}'{
"api_key": "ap_live_TlF0...KRNp",
"balance": 25,
"credits_included": 25,
"topup_url": "https://checkout.nanocorp.so/c/QfsWt42Pnik0EmvWOyvr"
}Step 2
Check the live balance
Pass the returned key as either Authorization: Bearer or X-API-Key. New wallets currently receive 25 trial credits.
API_KEY="ap_live_..." # paste the api_key from registration
curl -sS "$BASE/api/demo/balance" \
-H "Authorization: Bearer $API_KEY"{
"status": "success",
"mode": "live",
"agent_name": "curl-launch-bot",
"balance": 25,
"credits_included": 25,
"topup_url": "https://checkout.nanocorp.so/c/QfsWt42Pnik0EmvWOyvr"
}Step 3
Let the agent attempt a payment
A payment is a POST with an amount and a recipient identifier. Here the agent spends 1 credit on a hypothetical weather service.
curl -sS -X POST "$BASE/api/pay" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount":1,"to":"weather-agent"}'{
"status": "success",
"mode": "live",
"tx_id": "live-d40dafc9",
"balance_after": 24,
"topup_url": "https://checkout.nanocorp.so/c/QfsWt42Pnik0EmvWOyvr"
}Step 4
Handle insufficient balance like a product flow
When the requested payment exceeds the wallet balance, AgentPay returns 402 insufficient_balance. This is useful: your agent can pause, surface the top-up link, and continue after the operator buys credits.
curl -sS -w '
HTTP %{http_code}
' -X POST "$BASE/api/pay" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount":1000,"to":"research-agent"}'{
"error": "insufficient_balance",
"current_balance": 24,
"topup_url": "https://checkout.nanocorp.so/c/QfsWt42Pnik0EmvWOyvr",
"how_to_pay": "Surface topup_url to your human operator; after they complete checkout with this agent's registered email, call POST /api/redeem with this API key to apply the credits."
}
HTTP 402Top up here: $10 Agent Credits Pack. After checkout, call POST /api/redeem with the same API key to apply purchased credits.
Python
The full requests version
If you prefer one runnable file over shell commands, this script registers a wallet, checks balance, spends 1 credit, then intentionally asks for 1,000 credits to show the 402 path.
import json
import requests
BASE = "https://agentpay.nanocorp.app"
wallet = requests.post(
f"{BASE}/api/register-agent",
json={"agent_name": "requests-launch-bot", "email": "launch-requests@agentpay.nanocorp.app"},
timeout=20,
).json()
key = wallet["api_key"]
headers = {"Authorization": f"Bearer {key}"}
print(json.dumps({**wallet, "api_key": key[:12] + "..." + key[-4:]}, indent=2))
print(json.dumps(requests.get(f"{BASE}/api/demo/balance", headers=headers, timeout=20).json(), indent=2))
print(json.dumps(requests.post(f"{BASE}/api/pay", headers=headers, json={"amount": 1, "to": "weather-agent"}, timeout=20).json(), indent=2))
response = requests.post(
f"{BASE}/api/pay",
headers=headers,
json={"amount": 1000, "to": "research-agent"},
timeout=20,
)
print(response.status_code)
print(json.dumps(response.json(), indent=2))LangChain
Expose AgentPay as a tool
Tool-calling agents should not hide payments inside prompts. Make payment an explicit tool that returns structured JSON, including a top-up action when the wallet is short.
python -m pip install langchain-core requestsimport json
import os
import requests
from langchain_core.tools import tool
BASE_URL = "https://agentpay.nanocorp.app"
API_KEY = os.environ["AGENTPAY_API_KEY"]
@tool
def pay_with_agentpay(amount: float, to: str) -> dict:
"""Pay another agent or service provider with AgentPay credits."""
response = requests.post(
f"{BASE_URL}/api/pay",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"amount": amount, "to": to},
timeout=20,
)
if response.status_code == 402:
return {"needs_human_topup": True, **response.json()}
response.raise_for_status()
return response.json()
print(json.dumps(pay_with_agentpay.invoke({"amount": 1000, "to": "research-agent"}), indent=2)){
"needs_human_topup": true,
"error": "insufficient_balance",
"current_balance": 24,
"topup_url": "https://checkout.nanocorp.so/c/QfsWt42Pnik0EmvWOyvr",
"how_to_pay": "Surface topup_url to your human operator; after they complete checkout with this agent's registered email, call POST /api/redeem with this API key to apply the credits."
}Build the paid-agent loop
Give your agent spend permissions today.
Start with 25 trial credits, test the 402 path, then top up with the $10 Agent Credits Pack when your workflow is ready for real autonomous purchases.