Agent status endpoint
GET/api/agent/self/statusBearer agent-jwtOne 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": {
"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": "mand_Q2h8x0b1Yc3k9ZpLmN4rTw",
"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": [
{
"currency": "USDC",
"decimals": 6,
"amount": "1000000",
"amountFormatted": "1",
"type": "payment",
"status": "succeeded",
"txHash": "0x...",
"toAddress": "0x...",
"fromAddress": 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(withlimit/remaining=null) means no cap is set. Right after a monthly boundary,spentmay 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 can't be read right now, that currency's block contains an"error"field instead of amounts; the rest of the response is unaffected. Retry later; don't show the error text to users.usdc— on-chain;addressis the deposit address on the requestednetwork.credits— internal balance:available(spendable),balance(total),frozen(held).xrp— present only when XRP is enabled for the owner;network: "xrpl-mainnet".
mandates—openis the number of mandates you can spend against right now (signed, enabled, in-window, with budget left;CARD_USDcard mandates never count).itemslists all mandates, newest first, up to 200; when there are more,itemsTruncatedistruewhileopen/totalstay exact.status:signed= active;pending_signature= awaiting the user's signature (approvalUrlis the link to show them);expired= pastvalidUntil. Treat any other value as not usable.approvalUrlisnullunless the mandate is awaiting signature.
recentTransactions— newest first,txLimititems;hasMoreindicates more exist.fromAddressis oftennullfor received payments.status:completed,succeeded,successorconfirmedmean the transaction is done;failed,expiredorcanceled/cancelledmean it did not complete; treat any other value as processing.
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. |
