Agent status endpoint

One aggregate, read-only call that returns everything an agent can see about itself: profile, monthly spend headroom, balances (USDC / credits / XRP, each with its deposit address), authorized mandates, and recent transactions. Safe to poll — it never mutates any counter.

Request:

curl "https://walletapi.fluxapay.xyz/api/agent/self/status?network=base&txLimit=20" \
  -H "Authorization: Bearer $JWT_TOKEN"

Use the plain AgentID JWT — not the VC token

Authenticate with the agent's AgentID JWT (the token from agent registration). Sending an Agent VC token (typ=agent-vc) returns 401 wrong_token_type. This is the opposite of Verifiable Credential, which requires the VC token.

Query parameters (both optional):

Param	Default	Description
network	base	EVM network for the USDC balance lookup.
txLimit	20	Number of recent transactions to return (clamped to 1–100).

Response (200):

{
  "status": "ok",
  "agent": {
    "id": 123,
    "externalAgentId": "agent_abc",
    "name": "My Agent",
    "isAuthorized": true,
    "authorizationExpiry": "2026-12-31T00:00:00.000Z",
    "walletAddress": "0xYourAgentWallet",
    "monthly": {
      "decimals": 6,
      "unlimited": false,
      "limit": "100000000",
      "limitFormatted": "100",
      "spent": "12500000",
      "spentFormatted": "12.5",
      "pending": "0",
      "pendingFormatted": "0",
      "remaining": "87500000",
      "remainingFormatted": "87.5",
      "lastReset": "2026-06-01T00:00:00.000Z"
    }
  },
  "balances": {
    "usdc": {
      "network": "base",
      "address": "0xYourAgentWallet",
      "decimals": 6,
      "available": "87500000",
      "availableFormatted": "87.5"
    },
    "credits": {
      "decimals": 2,
      "available": "5000",
      "availableFormatted": "50",
      "balance": "6000",
      "balanceFormatted": "60",
      "frozen": "1000",
      "frozenFormatted": "10"
    }
  },
  "mandates": {
    "open": 1,
    "total": 3,
    "items": [
      {
        "mandateId": "mandate_xyz",
        "status": "signed",
        "isEnabled": true,
        "currency": "USDC",
        "decimals": 6,
        "naturalLanguage": "Pay up to 100 USDC this month",
        "category": "api",
        "limitAmount": "100000000",
        "limitAmountFormatted": "100",
        "spentAmount": "12500000",
        "spentAmountFormatted": "12.5",
        "pendingSpentAmount": "0",
        "pendingSpentAmountFormatted": "0",
        "remainingAmount": "87500000",
        "remainingAmountFormatted": "87.5",
        "validFrom": "2026-06-01T00:00:00.000Z",
        "validUntil": "2026-07-01T00:00:00.000Z",
        "signedAt": "2026-06-01T00:00:00.000Z",
        "createdAt": "2026-06-01T00:00:00.000Z",
        "approvalUrl": null
      }
    ],
    "itemsTruncated": false
  },
  "recentTransactions": {
    "items": [
      {
        "id": 999,
        "currency": "USDC",
        "decimals": 6,
        "amount": "1000000",
        "amountFormatted": "1",
        "type": "payment",
        "status": "completed",
        "txHash": "0x...",
        "toAddress": "0x...",
        "fromAddress": null,
        "failureReason": null,
        "createdAt": "2026-06-28T12:00:00.000Z"
      }
    ],
    "limit": 20,
    "hasMore": false
  }
}

Units

Every amount comes as three fields on the same block: an atomic integer string (<field>), a human-readable decimal string (<field>Formatted), and decimals. So you never have to guess the unit. USDC / XRP use 6 decimals, credits use 2. See Units & Networks.

Field notes

• agent.monthly — the agent's monthly spend headroom (a single counter across all currencies, atomic 6-decimal). unlimited: true (with limit/remaining = null) means no cap is set. Right after a monthly boundary, spent may briefly lag until the next payment resets the window — it only ever under-reports how much you've spent, never over.
• balances — best-effort per currency. If a balance lookup is slow or fails, that currency's block carries an "error" field instead of a value (the rest of the response still returns).
  • usdc — on-chain; address is the deposit address on the requested network.
  • credits — internal balance: available (spendable), balance (total), frozen (held).
  • xrp — present only when XRP is enabled for the owner; network: "xrpl-mainnet".
• mandates — open is the count of mandates you can actually spend against right now (signed, enabled, in-window, with budget left), always computed over the full set. items lists every mandate (including pending and expired), up to 200; when there are more, itemsTruncated is true while open/total stay exact.
  • status is the effective status: a mandate past its validUntil reads expired even if it was signed.
  • approvalUrl is a link to sign a mandate that's waiting for the user (pending_signature); it's null once the mandate is signed/active/expired.
• recentTransactions — newest first, txLimit per page; hasMore indicates more exist. fromAddress is often null for received payments.

Errors

HTTP	Body	Meaning
401	{ "error": "wrong_token_type" }	An Agent VC token was sent; this endpoint needs the plain AgentID JWT.
401 / 403	{ "status": "error", "code": "agent_auth_failed", "message": "…" }	The AgentID JWT is missing, invalid, or expired.
403	{ "status": "error", "code": "agent_not_authorized" }	The agent is deleted or not authorized.