Documentation / SDK v1

Wallet

Wallet balance and payout affordability checks via /sdk/v1.

wallet · json
{
  "success": true,
  "data": {
    "balanceValue": 1234.56,
    "spendValue": 789.01,
    "pendingValue": 50.0,
    "currency": "USD",
    "lowBalanceAlert": {
      "enabled": true,
      "thresholdValue": 1000,
      "thresholdCurrency": "EUR",
      "triggered": false,
      "lastNotifiedAt": null
    }
  }
}
All documentation

All endpoints below require:

  • X-Application-Id
  • X-Api-Key

GET /sdk/v1/wallet/balance

Get the agency wallet balance summary.

Response

{
  "success": true,
  "data": {
    "balanceValue": 1234.56,
    "spendValue": 789.01,
    "pendingValue": 50.0,
    "currency": "USD",
    "lowBalanceAlert": {
      "enabled": true,
      "thresholdValue": 1000,
      "thresholdCurrency": "EUR",
      "triggered": false,
      "lastNotifiedAt": null
    }
  }
}

lowBalanceAlert describes your low balance alert. It is read-only here; see Low balance alerts.

Field Type Meaning
enabled boolean Whether the alert is turned on.
thresholdValue number or null The threshold amount, in thresholdCurrency. null when no threshold is set.
thresholdCurrency string The ISO currency code the threshold was set in, such as EUR.
triggered boolean true once an alert has been sent and the balance has not yet recovered above the threshold.
lastNotifiedAt string or null When the last alert was sent (ISO 8601), or null if none has been.

Older integrations can ignore the field; nothing else in the response changed.

POST /sdk/v1/wallet/check-payout-balance

Check whether the wallet can cover a payout (including platform fee and settlement rules).

This endpoint returns a bare { sufficient: boolean } object (no success wrapper).

Body

Uses the same payload rules as POST /sdk/v1/payouts/trigger, except payoutRecipientEmail is optional.

If you include platformFeePayerOverride and, when needed, platformFeeAgencySharePercent, the affordability check uses that override when calculating the required wallet debit.

{
  "payoutCurrency": "USD",
  "payoutAmount": "5.00",
  "platformFeePayerOverride": "AGENCY_PAYS_ALL"
}

Response

{ "sufficient": true }

Common errors

  • 400: invalid payload (currency not supported, >2 decimals, missing amount, etc.)
  • 401: missing/invalid SDK headers
  • 403: origin not allowed (when allowlist is configured and Origin is present)

POST /sdk/v1/wallet/check-payout-balance-bulk

Check whether the wallet can cover the total of up to 100 payouts.

This endpoint returns a bare { sufficient: boolean } object (no success wrapper).

Body

{
  "payouts": [
    { "payoutCurrency": "USD", "payoutAmount": "5.00" },
    {
      "payoutCurrency": "USD",
      "payoutAmount": "10.00",
      "platformFeePayerOverride": "CUSTOM_SPLIT",
      "platformFeeAgencySharePercent": 25
    }
  ]
}

Response

{ "sufficient": false }

Low balance alerts

A low balance alert tells you once when your wallet balance falls below an amount you choose. Set it up in the Grade app under Developer > Notifications: turn on the alert, pick the threshold amount and its currency (USD, CAD, GBP or EUR), and choose who gets the email. The SDK can read these settings but cannot change them.

How you receive it

  • Email to the recipients you chose. You can turn email off and keep the other channels.
  • Slack or Discord, through your organization's chat integrations. Turn on Wallet balance low under Settings > Organization > Notifications (Integrations in the classic app).
  • Generic webhook, in the same place. This is the way to get a push in your own systems.
  • Polling. Read lowBalanceAlert.triggered from GET /sdk/v1/wallet/balance.

There is no webhook for SDK keys; the generic webhook is configured in the Grade dashboard.

When an alert is sent

  • You get one alert when the balance falls below the threshold.
  • No further alert is sent until the balance has gone back above the threshold. After that, the next drop below it sends a new one.
  • Exchange-rate changes alone never send an alert and never re-arm one. Your balance is held in USD, so Grade compares it with a fixed USD value of your threshold. That value follows the exchange rate only while your balance is above it, so only real money moving out of the wallet can cross it. The balance in the alert uses the same rate as the comparison.
  • Saving a changed threshold, currency, or on/off setting starts over: the next drop below the new threshold sends an alert.

Grade checks balances every few minutes and right after a payout, so an alert can arrive a few minutes after the balance falls.

Webhook payload

The generic webhook receives a POST with a JSON body. code is wallet.low_balance. data.eventMetadata holds the amounts, both in the threshold currency, and the same sentence used in the email and in Slack or Discord.

{
  "code": "wallet.low_balance",
  "event": "WALLET_LOW_BALANCE",
  "message": "Your Grade wallet balance is EUR 950.00, below your EUR 1,000.00 alert threshold.",
  "data": {
    "agencyId": "8f6c2a4e-0000-4000-8000-000000000000",
    "agencyName": "Example Agency",
    "campaignId": null,
    "creatorId": null,
    "campaignName": null,
    "campaignStatus": null,
    "campaignBrandName": null,
    "campaignCreatorCount": null,
    "creatorName": null,
    "actorName": null,
    "eventMetadata": {
      "balance": 950,
      "threshold": 1000,
      "currency": "EUR",
      "message": "Your Grade wallet balance is EUR 950.00, below your EUR 1,000.00 alert threshold."
    }
  },
  "test": false,
  "settingsUrl": "https://app.usegrade.com/settings/organization/integrations",
  "timestamp": "2026-11-19T14:05:00.000Z"
}

The campaign and creator fields are always null for this event. settingsUrl opens your integration settings in the Grade app, and test is true only for a test message sent from those settings.

The webhook is unsigned, so treat the call as a hint and read GET /sdk/v1/wallet/balance for the current balance and alert state.

Describe your program.

Grade turns it into a program it can track and pay.