How to create and manage Axis wallets for your AI agents

A wallet is a scoped spending account for one AI agent. Set per-transaction limits, period caps, expiry, and optional merchant allowlists at creation time.

A Wallet is the core primitive in Axis. Every AI agent you deploy gets its own wallet — a scoped spending account that constrains exactly how much the agent can spend, over what time window, with which merchants, and until when. You define all of these rules at creation time. Wallet rules cannot be changed after creation, so configure them carefully before issuing the wallet to an agent.

All monetary amounts — spendLimitPerTx, spendLimitPeriod, and any balance values — are integers in kobo, the smallest unit of the Nigerian Naira. ₦1 = 100 kobo. For example, a ₦5,000 transaction limit is represented as 500000.

---

Create a wallet

Send a POST request to /api/wallets with the configuration for your new agent wallet. The response includes the wallet record, a virtual bank account for funding, and a one-time API key for the agent to use.

POST /api/wallets

Request body

Field	Type	Required	Description
name	string	✅	Human-readable label for this wallet, e.g. "Purchasing Agent v1". 1–100 characters.
userId	string	✅	The user ID returned during signup. Links the wallet to the owning user account.
spendLimitPerTx	integer	✅	Maximum spend allowed in a single transaction, in kobo. Must be positive and ≤ spendLimitPeriod.
spendLimitPeriod	integer	✅	Maximum cumulative spend within the rolling period window, in kobo. Must be positive.
periodWindowDays	integer	✅	Length of the rolling spend window in days. Defaults to 30. Must be positive.
expiry	string	—	ISO 8601 datetime at which the wallet becomes inactive, e.g. "2027-01-01T00:00:00.000Z". Must be a future timestamp.
useAllowlist	boolean	—	When true, the wallet can only make payments to merchants in merchantAllowlist. Defaults to false.
merchantAllowlist	string[]	Conditional	Required when useAllowlist is true. List of merchant names the agent is permitted to pay. Must contain at least one entry.

Validation rules

Keep these constraints in mind when building your wallet creation form:

• spendLimitPerTx must be less than or equal to spendLimitPeriod.
• If expiry is provided, it must be a future datetime. Submitting a past or present timestamp will be rejected.
• If useAllowlist is true, merchantAllowlist must contain at least one merchant name.

Example request

POST /api/wallets

{
  "name": "Purchasing Agent v1",
  "userId": "user_2xKj9mNpQrT4vW8",
  "spendLimitPerTx": 500000,
  "spendLimitPeriod": 2000000,
  "periodWindowDays": 30,
  "expiry": "2027-01-01T00:00:00.000Z",
  "useAllowlist": false
}

Example response

The response body wraps three objects: the wallet record, a virtual bank account for funding, and a one-time API key.

201 Created

{
  "success": true,
  "data": {
    "wallet": {
      "id": "uuid",
      "name": "Purchasing Agent v1",
      "userId": "user_2xKj9mNpQrT4vW8",
      "balance": 0,
      "spendLimitPerTx": 500000,
      "spendLimitPeriod": 2000000,
      "periodWindowDays": 30,
      "useAllowlist": false,
      "expiry": "2027-01-01T00:00:00.000Z",
      "status": "ACTIVE",
      "createdAt": "2026-07-21T09:00:00.000Z"
    },
    "virtualAccount": {
      "id": "uuid",
      "walletId": "uuid",
      "accountNumber": "9876543210",
      "accountName": "Purchasing Agent v1",
      "bankName": "Providus Bank",
      "providerRef": "mock-ref-abc"
    },
    "apiKey": {
      "id": "uuid",
      "keyPrefix": "ax_live_9f2a3b",
      "fullKey": "ax_live_9f2a3b...",
      "createdAt": "2026-07-21T09:00:00.000Z"
    }
  }
}

The response contains three nested objects:

• data.wallet — the wallet record with all configuration and current balance.
• data.virtualAccount — the bank account details used to fund this wallet. Share accountNumber, accountName, and bankName with whoever needs to top up the agent’s balance.
• data.apiKey — the API key the agent uses to authenticate payment requests. Contains fullKey only in this response — it is never returned again.

Save apiKey.fullKey immediately. Axis stores only a hashed version of the key. After this response, only the keyPrefix is visible — the fullKey cannot be recovered. If it is lost, you must revoke the key and issue a new one.

---

Retrieve a wallet

Fetches the full wallet record, its linked virtual account, and a list of its API keys (prefixes only — no fullKey).

GET /api/wallets/:walletId

Example response

200 OK

{
  "success": true,
  "data": {
    "wallet": {
      "id": "uuid",
      "name": "Purchasing Agent v1",
      "userId": "user_2xKj9mNpQrT4vW8",
      "status": "ACTIVE",
      "spendLimitPerTx": 500000,
      "spendLimitPeriod": 2000000,
      "periodWindowDays": 30,
      "balance": 120000,
      "expiry": "2027-01-01T00:00:00.000Z",
      "useAllowlist": false,
      "createdAt": "2026-07-21T09:00:00.000Z"
    },
    "virtualAccount": {
      "id": "uuid",
      "walletId": "uuid",
      "accountNumber": "9876543210",
      "accountName": "Purchasing Agent v1",
      "bankName": "Providus Bank",
      "providerRef": "mock-ref-abc"
    },
    "apiKeys": [
      {
        "id": "uuid",
        "keyPrefix": "ax_live_9f2a3b",
        "createdAt": "2026-07-21T09:00:00.000Z"
      }
    ]
  }
}

Note that apiKeys is an array — a wallet may have multiple keys (e.g. after a rotation). Each entry shows only keyPrefix, not fullKey.

---

List wallets for a user

Returns all wallets associated with a given user ID.

GET /api/wallets/user/:userId

Example response

200 OK

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Purchasing Agent v1",
      "userId": "user_2xKj9mNpQrT4vW8",
      "status": "ACTIVE",
      "spendLimitPerTx": 500000,
      "spendLimitPeriod": 2000000,
      "periodWindowDays": 30,
      "balance": 120000,
      "expiry": "2027-01-01T00:00:00.000Z",
      "useAllowlist": false,
      "createdAt": "2026-07-21T09:00:00.000Z"
    },
    {
      "id": "uuid-2",
      "name": "Travel Booking Agent",
      "userId": "user_2xKj9mNpQrT4vW8",
      "status": "INACTIVE",
      "spendLimitPerTx": 1000000,
      "spendLimitPeriod": 10000000,
      "periodWindowDays": 7,
      "balance": 0,
      "expiry": "2026-12-31T23:59:59.000Z",
      "useAllowlist": false,
      "createdAt": "2026-07-18T14:30:00.000Z"
    }
  ]
}

---

Wallet status values

Every wallet has a status field that reflects its current state:

Status	Meaning
ACTIVE	The wallet is operational. The agent can initiate payment intents up to its configured limits.
INACTIVE	The wallet has been manually deactivated. Payment attempts will be declined.
EXPIRED	The wallet’s expiry datetime has passed. It is permanently inactive and cannot be reactivated. Create a new wallet to replace it.

---

React hook example

The hook below wraps the wallet creation endpoint, stores the apiKey.fullKey securely, and clears it from memory once you have handed it to your secret store.

src/hooks/useCreateWallet.ts

import { useState } from "react";

interface CreateWalletPayload {
  name: string;
  userId: string;
  spendLimitPerTx: number;
  spendLimitPeriod: number;
  periodWindowDays: number;
  expiry?: string;
  useAllowlist: boolean;
  merchantAllowlist?: string[];
}

interface VirtualAccount {
  id: string;
  walletId: string;
  accountNumber: string;
  accountName: string;
  bankName: string;
  providerRef: string;
}

interface ApiKey {
  id: string;
  keyPrefix: string;
  fullKey: string;
  createdAt: string;
}

interface Wallet {
  id: string;
  name: string;
  userId: string;
  status: "ACTIVE" | "INACTIVE" | "EXPIRED";
  spendLimitPerTx: number;
  spendLimitPeriod: number;
  periodWindowDays: number;
  balance: number;
  expiry?: string;
  useAllowlist: boolean;
  createdAt: string;
}

interface CreateWalletResult {
  wallet: Wallet;
  virtualAccount: VirtualAccount;
  apiKey: ApiKey;
}

interface UseCreateWalletReturn {
  createWallet: (payload: CreateWalletPayload) => Promise<CreateWalletResult>;
  loading: boolean;
  error: string | null;
}

export function useCreateWallet(apiBaseUrl = "/api"): UseCreateWalletReturn {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  async function createWallet(
    payload: CreateWalletPayload
  ): Promise<CreateWalletResult> {
    // Validate before hitting the network
    if (payload.spendLimitPerTx > payload.spendLimitPeriod) {
      throw new Error("spendLimitPerTx must be ≤ spendLimitPeriod");
    }
    if (payload.expiry && new Date(payload.expiry) <= new Date()) {
      throw new Error("expiry must be a future datetime");
    }
    if (payload.useAllowlist && !payload.merchantAllowlist?.length) {
      throw new Error(
        "merchantAllowlist must have at least one entry when useAllowlist is true"
      );
    }

    setLoading(true);
    setError(null);

    try {
      const response = await fetch(`${apiBaseUrl}/wallets`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        credentials: "include",
        body: JSON.stringify(payload),
      });

      if (!response.ok) {
        const err = await response.json().catch(() => ({}));
        throw new Error(
          err?.message ?? `Wallet creation failed (${response.status})`
        );
      }

      const result = await response.json();
      const data: CreateWalletResult = result.data;

      // ⚠️  fullKey is only present in this response — persist it to a
      // secure store (e.g. an encrypted backend vault or your secrets
      // manager) before this function returns. Never log it or store it
      // in localStorage / sessionStorage.
      await persistApiKey(data.apiKey.fullKey, data.wallet.id);

      return data;
    } catch (err) {
      const message =
        err instanceof Error ? err.message : "Wallet creation failed";
      setError(message);
      throw err;
    } finally {
      setLoading(false);
    }
  }

  return { createWallet, loading, error };
}

/**
 * Replace with your own secret storage logic.
 * The fullKey should be sent server-side and stored encrypted —
 * never kept in browser storage.
 */
async function persistApiKey(fullKey: string, walletId: string): Promise<void> {
  await fetch("/api/internal/store-key", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    credentials: "include",
    body: JSON.stringify({ walletId, fullKey }),
  });
}

Usage in a component

src/components/CreateWalletForm.tsx

import { useCreateWallet } from "../hooks/useCreateWallet";

export function CreateWalletForm({ userId }: { userId: string }) {
  const { createWallet, loading, error } = useCreateWallet();

  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();

    const wallet = await createWallet({
      name: "Purchasing Agent v1",
      userId,
      spendLimitPerTx: 500_000,    // ₦5,000 in kobo
      spendLimitPeriod: 2_000_000, // ₦20,000 in kobo
      periodWindowDays: 30,
      expiry: "2027-01-01T00:00:00.000Z",
      useAllowlist: false,
    });

    console.log("Wallet created:", wallet.wallet.id);
    console.log("Fund via:", wallet.virtualAccount.accountNumber);
    // wallet.apiKey.fullKey has already been persisted by the hook
  }

  return (
    <form onSubmit={handleSubmit}>
      {error && <p style={{ color: "red" }}>{error}</p>}
      <button type="submit" disabled={loading}>
        {loading ? "Creating wallet…" : "Create wallet"}
      </button>
    </form>
  );
}