Get live wallet statistics, balance, and spend limits

The stats endpoint gives you a pre-aggregated spend summary for a wallet — perfect for building a dashboard overview card without aggregating transactions yourself. A single request returns the current balance, configured spend limits, and how much of the period allowance has already been consumed.

Endpoints

`GET /v1/wallets/:id/stats`

Returns aggregated statistics for a single wallet. No query parameters required. Example response

{
  "balance": 1000000,
  "spendLimitPerTx": 500000,
  "spendLimitPeriod": 2000000,
  "spentThisPeriod": 500000,
  "remainingAllowance": 1500000
}

Stats fields

Field	Type	Description
`balance`	number	Current wallet balance in kobo — divide by 100 to display in naira
`spendLimitPerTx`	number	Maximum amount allowed per individual transaction, in kobo
`spendLimitPeriod`	number	Total spend cap for the current period, in kobo
`spentThisPeriod`	number	Amount already spent in the current period, in kobo
`remainingAllowance`	number	Remaining spendable amount in the current period (`spendLimitPeriod - spentThisPeriod`), in kobo

`GET /v1/wallets/:id/transactions`

Returns the most recent transactions for a wallet. Use the limit parameter to control how many records come back. Query parameters

Parameter	Type	Default	Description
`limit`	number	`20`	Maximum number of transactions to return

Each transaction record includes: amount, merchant, decision, reason, and createdAt. Pair this with the stats endpoint to populate both the summary card and the recent activity list in a single render cycle.

React example: stats dashboard card

The component below fetches wallet stats, converts kobo to naira for display, and renders a period-spend progress bar alongside balance and limit information.

import { useEffect, useState } from "react";

interface WalletStats {
  balance: number;
  spendLimitPerTx: number;
  spendLimitPeriod: number;
  spentThisPeriod: number;
  remainingAllowance: number;
}

interface WalletStatsCardProps {
  walletId: string;
  apiKey: string;
}

function koboToNaira(kobo: number): string {
  return (kobo / 100).toLocaleString("en-NG", {
    style: "currency",
    currency: "NGN",
  });
}

export function WalletStatsCard({ walletId, apiKey }: WalletStatsCardProps) {
  const [stats, setStats] = useState<WalletStats | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const fetchStats = async () => {
      try {
        const res = await fetch(`/v1/wallets/${walletId}/stats`, {
          headers: { Authorization: `Bearer ${apiKey}` },
        });
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        const json: WalletStats = await res.json();
        setStats(json);
      } catch (err) {
        setError(err instanceof Error ? err.message : "Failed to load stats");
      }
    };

    fetchStats();
  }, [walletId, apiKey]);

  if (error)   return <p className="text-red-500">Error: {error}</p>;
  if (!stats)  return <p className="text-gray-400">Loading stats…</p>;

  const spendPercent = stats.spendLimitPeriod > 0
    ? Math.min((stats.spentThisPeriod / stats.spendLimitPeriod) * 100, 100)
    : 0;

  return (
    <div className="rounded-xl border border-gray-200 bg-white p-6 shadow-sm space-y-4">
      <div>
        <p className="text-sm text-gray-500">Current Balance</p>
        <p className="text-3xl font-bold text-gray-900">
          {koboToNaira(stats.balance)}
        </p>
      </div>

      <div>
        <div className="flex justify-between text-sm text-gray-600 mb-1">
          <span>Period Spend</span>
          <span>
            {koboToNaira(stats.spentThisPeriod)} / {koboToNaira(stats.spendLimitPeriod)}
          </span>
        </div>
        <div className="h-2 w-full rounded-full bg-gray-100">
          <div
            className="h-2 rounded-full bg-indigo-500 transition-all"
            style={{ width: `${spendPercent}%` }}
          />
        </div>
      </div>

      <div className="grid grid-cols-2 gap-4 pt-2">
        <div className="rounded-lg bg-blue-50 p-3 text-center">
          <p className="text-2xl font-semibold text-blue-700">
            {koboToNaira(stats.remainingAllowance)}
          </p>
          <p className="text-xs text-blue-600">Remaining Allowance</p>
        </div>
        <div className="rounded-lg bg-gray-50 p-3 text-center">
          <p className="text-2xl font-semibold text-gray-700">
            {koboToNaira(stats.spendLimitPerTx)}
          </p>
          <p className="text-xs text-gray-600">Per-Tx Limit</p>
        </div>
      </div>
    </div>
  );
}

Polling for live updates

Axis uses short-polling rather than WebSockets. To keep your dashboard card current, set up a polling interval of 1–2 seconds on the stats endpoint. The useEffect hook below starts polling on mount and clears the interval when the component unmounts.

import { useEffect, useState, useRef } from "react";

function useWalletStats(walletId: string, apiKey: string, intervalMs = 1500) {
  const [stats, setStats] = useState<WalletStats | null>(null);
  const [error, setError] = useState<string | null>(null);
  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);

  useEffect(() => {
    const fetchStats = async () => {
      try {
        const res = await fetch(`/v1/wallets/${walletId}/stats`, {
          headers: { Authorization: `Bearer ${apiKey}` },
        });
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        const json: WalletStats = await res.json();
        setStats(json);
        setError(null);
      } catch (err) {
        setError(err instanceof Error ? err.message : "Unknown error");
      }
    };

    // Fetch immediately, then start polling
    fetchStats();
    intervalRef.current = setInterval(fetchStats, intervalMs);

    return () => {
      if (intervalRef.current) clearInterval(intervalRef.current);
    };
  }, [walletId, apiKey, intervalMs]);

  return { stats, error };
}

// Usage in a component:
export function LiveStatsCard({ walletId, apiKey }: { walletId: string; apiKey: string }) {
  const { stats, error } = useWalletStats(walletId, apiKey, 1500);

  if (error)  return <p className="text-red-500">Error: {error}</p>;
  if (!stats) return <p className="text-gray-400">Connecting…</p>;

  return <WalletStatsCard walletId={walletId} apiKey={apiKey} />;
}

The hook fetches once immediately, then re-fetches every intervalMs milliseconds. The cleanup function returned from useEffect cancels the interval when the component unmounts, preventing memory leaks and stale state updates.

The stats endpoint gives you the current aggregated balance and spend figures, but if you need the full immutable history of every balance change — top-ups, debits, and refunds — see Query the Axis ledger.

Overview

Authentication

Core Flows

Monitoring

Get live wallet statistics, balance, and spend limits

Endpoints

`GET /v1/wallets/:id/stats`

`GET /v1/wallets/:id/transactions`

React example: stats dashboard card

Polling for live updates

​Endpoints

​GET /v1/wallets/:id/stats

​GET /v1/wallets/:id/transactions

​React example: stats dashboard card

​Polling for live updates

Endpoints

`GET /v1/wallets/:id/stats`

`GET /v1/wallets/:id/transactions`

React example: stats dashboard card

Polling for live updates