Skip to main content

Wallet

Monitor your wallet balance and ensure sufficient funds for order processing.

Fetch Wallet Balance​

GET/v1/partners/wallet/balance

Returns your current wallet balance.

Example Request​

curl "https://api.myhubble.money/v1/partners/wallet/balance" \
  -H "Authorization: Bearer <prod_token>" \
  -H "X-REQUEST-ID: $(uuidgen)"

Response​

Status 200: Balance fetch successful

{
  "balance": 1000.50
}

Error Responses​

StatusMeaning
401Unauthorized
400Bad request, e.g., missing fields

Staging vs Production Wallet​

Important Differences

Staging:

  • You get a test balance that can be exhausted
  • Request a top-up from Hubble support when needed

Production:

  • The wallet holds real money
  • Orders are debited at the gross (full) amount
  • Ensure sufficient balance before going live

Handling Insufficient Balance​

When your wallet balance is too low to process an order, you'll receive error code E300.

E300 — Insufficient Wallet Balance

Monitor your balance proactively. Set up the Wallet Low Balance webhook for alerts before your wallet runs dry.

Example Error Response​

When placing an order with insufficient balance:

{
  "id": "E300",
  "code": "INSUFFICIENT_BALANCE",
  "message": "Insufficient wallet balance",
  "requestId": "req_12345"
}

Wallet Top-Up​

Wallet loading is an offline process. Contact your Hubble account manager to request a top-up.

Top-Up Process​

  1. Contact your Hubble account manager
  2. Request the top-up amount needed
  3. Complete the payment through agreed channels
  4. Balance will be credited to your wallet
Best Practice

Set up the Wallet Low Balance webhook to receive alerts when your balance falls below a threshold. This gives you time to initiate the top-up process before orders start failing.

Best Practices​

Monitor Balance Regularly​

// Example: Check balance before high-volume operations
async function checkBalanceBeforeOrders(orderTotal) {
  const response = await fetch('/v1/partners/wallet/balance', {
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-REQUEST-ID': generateUUID()
    }
  });

  const { balance } = await response.json();

  if (balance < orderTotal) {
    // Alert team, pause operations, or request top-up
    console.warn(`Low balance: ${balance}. Required: ${orderTotal}`);
    return false;
  }

  return true;
}

Set Up Webhook Alerts​

Configure the Wallet Low Balance webhook with an appropriate threshold based on your order volume:

  • Low volume: Set threshold to cover 1-2 days of orders
  • High volume: Set threshold to cover at least 1 day of orders

Track Balance Consumption​

Keep track of your order volume and balance consumption patterns to predict when top-ups are needed.