Billing
Check credits, transactions, and usage
Overview
The Billing API provides access to credits, transactions, and usage information for OAuth apps.
Authentication: OAuth token
Required Scopes: billing:read (read), billing:write (topup)
Important: Team-Based Billing
All billing is tied to teams, not individual users:
- Personal Team - Every user has a personal team where their credits are stored
- Shared Teams - Team owners/admins can view team billing
- Credits are shared - All team members use the same credit pool
When you call /api/wallet/balance, you get the balance for the user's currently active team (typically their personal team).
Billing runs in one of three modes — vag_passthrough (default; Vercel AI
Gateway emits Stripe meter events and the customer is billed directly, no credit
wallet), metered (credit wallet auto-charged to refill), or prepaid
(credit wallet, manual top-up). See Billing & Credits for
the full comparison and who is billed. The wallet endpoints below apply only to
the credit modes; in vag_passthrough there is no wallet, so
GET /api/wallet/state reports mode: "vag_passthrough" and the credit
balance is unused (reads 0) — usage is metered to Stripe directly.
Get Wallet State
A single mode-aware snapshot the React SDK renders its funds popup from.
Endpoint: GET /api/wallet/state
Response:
{
"mode": "metered",
"balance": 1250.50,
"paymentMethod": { "exists": true, "last4": "4242", "brand": "visa" },
"autoTopUp": { "enabled": true, "threshold": 200, "amount": 1000 },
"lowBalance": false,
"topupTiers": [10, 25, 50, 100]
}Get Balance
Check current credit balance.
Endpoint: GET /api/wallet/balance
const response = await fetch('https://hypery.ai/api/wallet/balance', {
headers: {
'Authorization': `Bearer ${oauthToken}`
}
})
const { balance } = await response.json()
console.log('Credits:', balance.credits)response = requests.get(
'https://hypery.ai/api/wallet/balance',
headers={'Authorization': f'Bearer {oauth_token}'}
)
balance = response.json()['balance']
print('Credits:', balance['credits'])curl https://hypery.ai/api/wallet/balance \
-H "Authorization: Bearer OAUTH_TOKEN"Response:
{
"success": true,
"balance": {
"credits": 1250.50,
"currency": "USD",
"lastUpdated": "2025-11-16T10:30:00Z"
}
}Output Fields
Get Transactions
View transaction history.
Endpoint: GET /api/wallet/transactions
const response = await fetch('https://hypery.ai/api/wallet/transactions', {
headers: {
'Authorization': `Bearer ${oauthToken}`
}
})
const { transactions } = await response.json()response = requests.get(
'https://hypery.ai/api/wallet/transactions',
headers={'Authorization': f'Bearer {oauth_token}'}
)
transactions = response.json()['transactions']curl https://hypery.ai/api/wallet/transactions \
-H "Authorization: Bearer OAUTH_TOKEN"Response:
{
"success": true,
"transactions": [
{
"id": "507f...",
"type": "credit",
"amount": 100.00,
"description": "Credit purchase",
"createdAt": "2025-11-16T10:00:00Z"
},
{
"id": "507f...",
"type": "debit",
"amount": -0.05,
"description": "AI API usage",
"createdAt": "2025-11-16T10:30:00Z"
}
]
}Transaction Fields
Get Usage Analytics
View usage statistics for a team.
Endpoint: GET /api/analytics/:slug
const response = await fetch(
`https://hypery.ai/api/analytics/${teamSlug}`,
{ headers: { 'Authorization': `Bearer ${oauthToken}` } }
)
const { analytics } = await response.json()response = requests.get(
f'https://hypery.ai/api/analytics/{team_slug}',
headers={'Authorization': f'Bearer {oauth_token}'}
)
analytics = response.json()['analytics']curl https://hypery.ai/api/analytics/TEAM_SLUG \
-H "Authorization: Bearer OAUTH_TOKEN"Response:
{
"success": true,
"analytics": {
"totalRequests": 1250,
"totalCost": 45.50,
"period": "month",
"breakdown": {
"chat": 1000,
"images": 250
}
}
}Get Payment Methods
List saved payment methods.
Endpoint: GET /api/wallet/payment-methods
const response = await fetch('https://hypery.ai/api/wallet/payment-methods', {
headers: {
'Authorization': `Bearer ${oauthToken}`
}
})
const { paymentMethods } = await response.json()response = requests.get(
'https://hypery.ai/api/wallet/payment-methods',
headers={'Authorization': f'Bearer {oauth_token}'}
)
methods = response.json()['paymentMethods']curl https://hypery.ai/api/wallet/payment-methods \
-H "Authorization: Bearer OAUTH_TOKEN"Response:
{
"success": true,
"paymentMethods": [
{
"id": "pm_123...",
"type": "card",
"last4": "4242",
"brand": "visa",
"isDefault": true
}
]
}Add Credits
Top up credits (requires billing:write scope).
Endpoint: POST /api/wallet/topup
const response = await fetch('https://hypery.ai/api/wallet/topup', {
method: 'POST',
headers: {
'Authorization': `Bearer ${oauthToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: 50.00
})
})
const result = await response.json()response = requests.post(
'https://hypery.ai/api/wallet/topup',
headers={'Authorization': f'Bearer {oauth_token}'},
json={'amount': 50.00}
)curl -X POST https://hypery.ai/api/wallet/topup \
-H "Authorization: Bearer OAUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{"amount": 50.00}'Input Parameters
This is the 1-click funding primitive: it charges the team's default card and adds credits in place. In metered mode the same charge path runs automatically as an auto top-up when the balance is low.
Topping up charges money. The caller must be a billing admin of the resolved team — the gateway authorizes every money-moving request against the token's team to prevent cross-tenant charges.