Use Wallgent with Any Agent (REST API)

Prerequisites

A Wallgent account and API key (get one here)
Any HTTP client (curl, Python requests, fetch, etc.)

Base URL

https://api.wallgent.com

All requests require a Bearer token:

Authorization: Bearer wg_test_your_key_here

1. curl Examples

Create a Wallet

curl -X POST https://api.wallgent.com/v1/wallets \
  -H "Authorization: Bearer wg_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "agentName": "my-bot"}'

Response:

{
  "id": "wal_01J...",
  "name": "My Agent",
  "agentName": "my-bot",
  "environment": "SANDBOX",
  "balance": "0.00000000",
  "currency": "USD"
}

Fund the Wallet

curl -X POST https://api.wallgent.com/v1/wallets/wal_01J.../fund \
  -H "Authorization: Bearer wg_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100.00}'

Send a Payment

curl -X POST https://api.wallgent.com/v1/payments \
  -H "Authorization: Bearer wg_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "wal_01J_source",
    "to": "wal_01J_dest",
    "amount": 25.00,
    "description": "API service fee"
  }'

Response:

{
  "id": "txn_01J...",
  "from": "wal_01J_source",
  "to": "wal_01J_dest",
  "amount": "25.00",
  "fee": "0.25",
  "status": "POSTED"
}

Check Balance

curl https://api.wallgent.com/v1/wallets/wal_01J.../balance \
  -H "Authorization: Bearer wg_test_your_key_here"

2. Python (requests)

import requests

API_KEY = "wg_test_your_key_here"
BASE = "https://api.wallgent.com"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# Create a wallet
wallet = requests.post(f"{BASE}/v1/wallets", headers=HEADERS, json={
    "name": "Python Agent",
    "agentName": "py-bot",
}).json()
wallet_id = wallet["id"]
print(f"Wallet: {wallet_id}")

# Fund it
requests.post(f"{BASE}/v1/wallets/{wallet_id}/fund", headers=HEADERS, json={
    "amount": 100.00,
})

# Check balance
balance = requests.get(
    f"{BASE}/v1/wallets/{wallet_id}/balance", headers=HEADERS
).json()
print(f"Balance: {balance['balance']} {balance['currency']}")

# Send a payment
payment = requests.post(f"{BASE}/v1/payments", headers=HEADERS, json={
    "from": wallet_id,
    "to": "wal_recipient_id",
    "amount": 10.00,
    "description": "Payment from Python",
}).json()
print(f"Payment: {payment['id']} — {payment['status']}")

3. TypeScript (fetch)

const API_KEY = 'wg_test_your_key_here';
const BASE = 'https://api.wallgent.com';

const headers = {
  Authorization: `Bearer ${API_KEY}`,
  'Content-Type': 'application/json',
};

// Create a wallet
const wallet = await fetch(`${BASE}/v1/wallets`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ name: 'Fetch Agent', agentName: 'fetch-bot' }),
}).then((r) => r.json());
console.log('Wallet:', wallet.id);

// Fund it
await fetch(`${BASE}/v1/wallets/${wallet.id}/fund`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ amount: 100.0 }),
});

// Check balance
const balance = await fetch(`${BASE}/v1/wallets/${wallet.id}/balance`, {
  headers,
}).then((r) => r.json());
console.log('Balance:', balance.balance, balance.currency);

// Send a payment
const payment = await fetch(`${BASE}/v1/payments`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    from: wallet.id,
    to: 'wal_recipient_id',
    amount: 25.0,
    description: 'Payment from fetch',
  }),
}).then((r) => r.json());
console.log('Payment:', payment.id, payment.status);

If you are using TypeScript, consider the SDK instead — it provides typed responses and error handling out of the box.

Error Handling

All errors follow a consistent format:

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Account balance too low"
  }
}

Common error codes:

Code	HTTP Status	Description
`INSUFFICIENT_FUNDS`	402	Wallet balance too low
`POLICY_DENIED`	403	A policy rule blocked the transaction
`WALLET_NOT_FOUND`	404	Wallet ID does not exist
`INVALID_AMOUNT`	400	Amount is zero, negative, or malformed
`UNAUTHORIZED`	401	Missing or invalid API key
`RATE_LIMIT_EXCEEDED`	429	Too many requests

See the full API Reference for all endpoints and error codes.

Next Steps

Use the TypeScript SDK for typed responses and error classes
Set up authentication with permissions and IP allowlists
Add webhooks for real-time event notifications

Use Wallgent with Any Agent (REST API)

On this page