For Developers
DashboardLog InGet an API key
Account

Wallet

Read your prepaid wallet balance, auto-recharge settings and transaction history.

Your wallet holds prepaid funds that pay for usage. This API is read-only. All money values are decimal amounts in dollars, not cents, so 123.50 means $123.50 USD.

EndpointRequest
Get wallet balanceGET/v1/wallet/balance
List wallet transactionsGET/v1/wallet/transactions

The wallet balance object

Fields use camelCase. Timestamps are left out when they have no value.

Attributes

idstringrequired
The wallet's UUID.
balancenumberrequired
The current balance in dollars. Funds held for calls in progress are not subtracted.
currencystringrequired
The wallet's currency code, in lowercase. New wallets use usd.
autoRechargeobjectrequired
The auto-recharge settings, described below.
lastRechargeAtstring
ISO 8601 time of the last recharge.
createdAtstring
ISO 8601 creation time.
updatedAtstring
ISO 8601 time of the last change.

autoRecharge attributes

enabledbooleanrequired
Whether auto-recharge is on.
thresholdnumberrequired
The balance in dollars that triggers a recharge. 0 when not set.
amountnumberrequired
The amount in dollars to add on each recharge. 0 when not set.

The transaction object

Transaction fields use snake_case, unlike the balance object.

Attributes

idstringrequired
The transaction's UUID.
wallet_idstringrequired
The wallet's UUID.
transaction_typestringrequired
The direction of the movement, such as debit or credit.
amountnumberrequired
The amount moved, in dollars. Use transaction_type for the direction.
balance_beforenumberrequired
The balance in dollars before this transaction.
balance_afternumberrequired
The balance in dollars after this transaction.
descriptionstringrequired
A readable description of the transaction.
created_atstringrequired
ISO 8601 creation time.

Get wallet balance

GET/v1/wallet/balanceread key

Returns your wallet's balance and auto-recharge settings. If your account has no wallet yet, this creates one with a balance of 0 and auto-recharge off.

Request
curl https://backend.synthesys.app/api/v1/wallet/balance \
  -H "SYNTH_API_KEY: YOUR_API_KEY"
Response
{
  "success": true,
  "data": {
    "id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "balance": 123.5,
    "currency": "usd",
    "autoRecharge": {
      "enabled": true,
      "threshold": 10,
      "amount": 50
    },
    "lastRechargeAt": "2026-10-01T09:00:00.000Z",
    "createdAt": "2026-06-15T12:00:00.000Z",
    "updatedAt": "2026-10-20T16:45:00.000Z"
  }
}

List wallet transactions

GET/v1/wallet/transactionsread key

Returns your wallet transactions, newest first. pagination.total is the true number of matching transactions.

Query parameters

limitintegerdefault 50
Maximum results, from 1 to 100.
offsetintegerdefault 0
Number of results to skip, up to 1,000,000.
start_datestring
Return transactions created at or after this time.
end_datestring
Return transactions created at or before this time. A date with no time means the end of that UTC day.

Send dates as YYYY-MM-DD or a full ISO 8601 time with a timezone, such as 2026-10-31T12:00:00Z. A date with no time means midnight UTC at the start of that day.

A limit or offset out of range, an invalid date, or a start_date after end_date returns 400.

Request
curl "https://backend.synthesys.app/api/v1/wallet/transactions?start_date=2026-10-01T00:00:00Z&limit=20" \
  -H "SYNTH_API_KEY: YOUR_API_KEY"
Response
{
  "success": true,
  "data": [
    {
      "id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      "wallet_id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "transaction_type": "debit",
      "amount": 1.5,
      "balance_before": 125,
      "balance_after": 123.5,
      "description": "Structured output analysis: 3 result(s)",
      "created_at": "2026-10-20T16:45:00+00:00"
    }
  ],
  "pagination": { "total": 1, "limit": 10, "offset": 0 }
}