GET /api/dashboard — Dashboard Summary Data

GET /api/dashboard — returns a unified summary of wallet balances, active sessions, pending approvals, policies, and monthly usage in one request.

The dashboard endpoint is your single entry point for building a complete account overview. One authenticated request returns seven data points — wallet balances, recent transactions, active AI sessions, pending approval requests, spending policies, monthly usage records, and per-session daily budget consumption. Rather than making seven separate API calls and stitching the results together on the client, you can use this endpoint to populate an entire dashboard UI in a single round trip.

This endpoint is purpose-built for dashboard UIs. All seven data sources are fetched concurrently on the server, so the total response time is bounded by the slowest individual source — not the sum of all seven. Use it wherever you need a full account snapshot and want to minimize network overhead.

Endpoint

GET /api/dashboard

Authentication

All requests must include a valid bearer token in the Authorization header, or a pay3_session cookie obtained during wallet authentication.

Authorization: Bearer <token>

Response fields

wallet · object · required

Wallet identity and live Stellar asset balances for your primary wallet.

Show wallet fields

wallet · object · required

Core wallet metadata.

Show wallet.wallet fields

id · string · required

UUID of the wallet record.

publicAddress · string · required

Stellar G-address (public key) for this wallet.

network · string · required

Stellar network this wallet operates on. One of TESTNET or PUBLIC.

isPrimary · boolean · required

Whether this is the account’s designated primary wallet.

balances · array · required

Live asset balances fetched directly from the Stellar network at request time. Each entry represents one asset held by the wallet.

Show balances[] fields

asset · string · required

Asset code (e.g. "USDC", "XLM").

balance · string · required

Current balance as a decimal string (e.g. "250.0000000").

assetType · string · required

Stellar asset type. One of native (XLM) or credit_alphanum4 / credit_alphanum12 for issued assets.

smartAccounts · array · required

Soroban smart account contracts linked to this wallet.

Show smartAccounts[] fields

id · string · required

UUID of the smart account record.

contractId · string · required

On-chain Soroban contract ID (C-address).

network · string · required

Stellar network the contract is deployed on.

createdAt · string · required

ISO 8601 timestamp when the smart account was created.

recentTransactions · array · required

The 10 most recent transactions across your account, ordered newest first.

Show recentTransactions[] fields

id · string · required

UUID of the transaction record.

action · string · required

Operation type. One of TRANSFER, CHECK_BALANCE, or VIEW_TRANSACTION_HISTORY.

status · string · required

Transaction lifecycle status. One of CREATED, VALIDATING, AUTO_APPROVED, PENDING_APPROVAL, APPROVED, SIGNING, SUBMITTING, SUCCESS, FAILED, REJECTED, EXPIRED, or CANCELLED.

amount · string

Transfer amount as a decimal string. null for non-transfer actions.

asset · string · required

Asset code (e.g. "USDC").

recipientAddress · string

Resolved Stellar G-address of the recipient. null for non-transfer actions.

stellarTransactionHash · string

On-chain transaction hash. Present only after the transaction has reached SUCCESS.

aiSession · object

The AI session that initiated this transaction.

Show aiSession fields

id · string · required

UUID of the AI session.

clientType · string · required

AI client that created this session (e.g. "CURSOR", "CLAUDE").

contact · object

The resolved contact for this transaction’s recipient, if the address matched a saved contact. null if no match was found.

Show contact fields

id · string · required

UUID of the contact record.

displayName · string · required

Human-readable name of the contact.

createdAt · string · required

ISO 8601 timestamp when the transaction record was created.

activeSessions · array · required

All currently active AI sessions on your account — sessions with status ACTIVE and a future expiresAt.

Show activeSessions[] fields

id · string · required

UUID of the AI session.

clientType · string · required

AI client associated with this session. One of CURSOR, CLAUDE, CHATGPT, GEMINI, or OTHER.

smartAccountId · string · required

UUID of the smart account this session is authorized to operate on.

policyId · string · required

UUID of the spending policy governing this session’s transaction limits.

status · string · required

Session status — ACTIVE for all entries in this array.

expiresAt · string · required

ISO 8601 timestamp when this session will automatically expire.

createdAt · string · required

ISO 8601 timestamp when the session was created.

pendingApprovals · array · required

All approval requests currently awaiting your review — requests with status PENDING and a future expiresAt.

Show pendingApprovals[] fields

id · string · required

UUID of the approval request.

status · string · required

Always PENDING for entries returned here.

transactionId · string · required

UUID of the transaction awaiting approval.

expiresAt · string · required

ISO 8601 timestamp after which this approval request expires and can no longer be actioned.

transaction · object · required

Full transaction record for the payment being requested.

Show transaction fields

id · string · required

UUID of the transaction.

action · string · required

Always TRANSFER for transactions that require approval.

amount · string · required

Requested transfer amount as a decimal string.

asset · string · required

Asset code to be transferred.

recipientAddress · string · required

Recipient’s Stellar G-address.

status · string · required

Transaction status — PENDING_APPROVAL for all entries in this context.

aiSession · object · required

The AI session that triggered this approval request.

Show aiSession fields

id · string · required

UUID of the AI session.

clientType · string · required

AI client that initiated the transaction.

createdAt · string · required

ISO 8601 timestamp when the approval request was created.

policies · array · required

All active spending policies on your account, ordered newest first.

Show policies[] fields

id · string · required

UUID of the policy.

name · string · required

Human-readable name you gave this policy.

preset · string · required

Policy preset used as the starting configuration. One of CONSERVATIVE, BALANCED, DEFI, or CUSTOM.

dailyBudget · string · required

Maximum total spend per day across all sessions using this policy, as a decimal string (USD).

monthlyBudget · string

Monthly spend cap in USD as a decimal string, or null if no monthly limit is set.

perTransactionMax · string · required

Maximum amount for a single transaction, as a decimal string (USD).

manualApprovalThreshold · string · required

Transactions above this amount (USD) require manual approval before submission.

sessionDurationHours · number · required

Maximum lifetime in hours for any session created under this policy.

allowedAssets · array · required

List of asset codes this policy permits (e.g. ["USDC", "XLM"]).

allowedActions · array · required

List of actions permitted under this policy. Values include CHECK_BALANCE, TRANSFER, and VIEW_TRANSACTION_HISTORY.

allowedRecipientIds · array · required

List of contact UUIDs that sessions under this policy may send to. An empty array means no recipient restriction is enforced.

rateLimitPerMinute · number

Maximum transactions per minute. null if no rate limit is set.

isActive · boolean · required

Whether this policy is currently active. Only active policies appear in this array.

createdAt · string · required

ISO 8601 timestamp when the policy was created.

updatedAt · string · required

ISO 8601 timestamp when the policy was last modified.

monthlyUsage · object · required

Aggregated spend records for the current calendar month, broken down by AI session and asset.

Show monthlyUsage fields

period · object · required

The billing period these records cover.

Show period fields

year · number · required

Four-digit calendar year (e.g. 2025).

month · number · required

Calendar month as an integer from 1 (January) to 12 (December).

records · array · required

Individual usage records, each representing spend for one session-and-asset combination.

Show records[] fields

aiSessionId · string · required

UUID of the AI session this record belongs to.

asset · string · required

Asset code for this usage record (e.g. "USDC").

totalAmount · string · required

Total amount transacted in this asset during the period, as a decimal string.

transactionCount · number · required

Number of transactions contributing to totalAmount.

totalsByAsset · object · required

Aggregated totals rolled up across all sessions, keyed by uppercase asset code.

Show totalsByAsset example

{
  "USDC": { "totalAmount": "320.50", "transactionCount": 7 },
  "XLM":  { "totalAmount": "45.00",  "transactionCount": 2 }
}

budgetUsage · object · required

Real-time daily and monthly budget consumption for every currently active AI session.

Show budgetUsage fields

sessions · array · required

One entry per active session. An empty array is returned if no sessions are currently active.

Show sessions[] fields

sessionId · string · required

UUID of the active AI session.

clientType · string · required

AI client type for this session (e.g. "CURSOR").

smartAccountId · string · required

UUID of the smart account this session is authorized to operate on.

policy · object · required

Spending limits in effect for this session.

Show policy fields

dailyBudget · string · required

Daily spend cap in USD as a decimal string.

monthlyBudget · string

Monthly spend cap in USD, or null if no monthly limit is set.

allowedAssets · array · required

Asset codes this session is permitted to transfer.

dailySpent · array · required

Amount spent today (UTC day) broken down by asset.

Show dailySpent[] fields

asset · string · required

Asset code (e.g. "USDC").

spentAmount · string · required

Amount spent today in this asset, as a decimal string.

monthlySpent · array · required

Amount spent in the current calendar month broken down by asset.

Show monthlySpent[] fields

asset · string · required

Asset code (e.g. "USDC").

spentAmount · string · required

Amount spent this month in this asset, as a decimal string.

Example request

curl https://api.pay3.dev/api/dashboard \
  -H "Authorization: Bearer <token>"

Example response

{
  "wallet": {
    "wallet": {
      "id": "w1a2b3c4-0001-4abc-8def-000000000001",
      "publicAddress": "GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37",
      "network": "PUBLIC",
      "isPrimary": true
    },
    "balances": [
      {
        "asset": "USDC",
        "balance": "1250.0000000",
        "assetType": "credit_alphanum4"
      },
      {
        "asset": "XLM",
        "balance": "98.4321000",
        "assetType": "native"
      }
    ],
    "smartAccounts": [
      {
        "id": "sa1a2b3c4-0001-4abc-8def-000000000010",
        "contractId": "CCJZ5DGASBWQXR5MPFCJXMBI5HONGSDJFQNZOQQVLRBTKMJZFJBTMKYT",
        "network": "PUBLIC",
        "createdAt": "2025-05-01T09:00:00.000Z"
      }
    ]
  },
  "recentTransactions": [
    {
      "id": "tx1a2b3c4-0001-4abc-8def-000000000020",
      "action": "TRANSFER",
      "status": "SUCCESS",
      "amount": "50.00",
      "asset": "USDC",
      "recipientAddress": "GBVFEQKQ5VGHIH4CVXOL5TXIVMS6OJQMQHM5LLNTV3AAJHID5OFWKM4",
      "stellarTransactionHash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
      "aiSession": {
        "id": "sess1a2b3c4-0001-4abc-8def-000000000030",
        "clientType": "CURSOR"
      },
      "contact": {
        "id": "c1a2b3d4-0001-4abc-8def-000000000001",
        "displayName": "Alice Johnson"
      },
      "createdAt": "2025-07-08T14:30:00.000Z"
    }
  ],
  "activeSessions": [
    {
      "id": "sess1a2b3c4-0001-4abc-8def-000000000030",
      "clientType": "CURSOR",
      "smartAccountId": "sa1a2b3c4-0001-4abc-8def-000000000010",
      "policyId": "pol1a2b3c4-0001-4abc-8def-000000000040",
      "status": "ACTIVE",
      "expiresAt": "2025-07-15T14:30:00.000Z",
      "createdAt": "2025-07-08T14:30:00.000Z"
    }
  ],
  "pendingApprovals": [
    {
      "id": "apr1a2b3c4-0001-4abc-8def-000000000050",
      "status": "PENDING",
      "transactionId": "tx1a2b3c4-0002-4abc-8def-000000000021",
      "expiresAt": "2025-07-09T14:32:00.000Z",
      "transaction": {
        "id": "tx1a2b3c4-0002-4abc-8def-000000000021",
        "action": "TRANSFER",
        "amount": "200.00",
        "asset": "USDC",
        "recipientAddress": "GBVFEQKQ5VGHIH4CVXOL5TXIVMS6OJQMQHM5LLNTV3AAJHID5OFWKM4",
        "status": "PENDING_APPROVAL"
      },
      "aiSession": {
        "id": "sess1a2b3c4-0001-4abc-8def-000000000030",
        "clientType": "CURSOR"
      },
      "createdAt": "2025-07-08T16:00:00.000Z"
    }
  ],
  "policies": [
    {
      "id": "pol1a2b3c4-0001-4abc-8def-000000000040",
      "name": "Daily Ops",
      "preset": "BALANCED",
      "dailyBudget": "500.0000000",
      "monthlyBudget": null,
      "perTransactionMax": "100.0000000",
      "manualApprovalThreshold": "250.0000000",
      "sessionDurationHours": 168,
      "allowedAssets": ["USDC", "XLM"],
      "allowedActions": [
        "CHECK_BALANCE",
        "TRANSFER",
        "VIEW_TRANSACTION_HISTORY"
      ],
      "allowedRecipientIds": [
        "c1a2b3d4-0001-4abc-8def-000000000001"
      ],
      "rateLimitPerMinute": null,
      "isActive": true,
      "createdAt": "2025-05-10T10:00:00.000Z",
      "updatedAt": "2025-05-10T10:00:00.000Z"
    }
  ],
  "monthlyUsage": {
    "period": {
      "year": 2025,
      "month": 7
    },
    "records": [
      {
        "aiSessionId": "sess1a2b3c4-0001-4abc-8def-000000000030",
        "asset": "USDC",
        "totalAmount": "320.50",
        "transactionCount": 7
      }
    ],
    "totalsByAsset": {
      "USDC": {
        "totalAmount": "320.50",
        "transactionCount": 7
      }
    }
  },
  "budgetUsage": {
    "sessions": [
      {
        "sessionId": "sess1a2b3c4-0001-4abc-8def-000000000030",
        "clientType": "CURSOR",
        "smartAccountId": "sa1a2b3c4-0001-4abc-8def-000000000010",
        "policy": {
          "dailyBudget": "500.0000000",
          "monthlyBudget": null,
          "allowedAssets": ["USDC", "XLM"]
        },
        "dailySpent": [
          {
            "asset": "USDC",
            "spentAmount": "50.00"
          }
        ],
        "monthlySpent": [
          {
            "asset": "USDC",
            "spentAmount": "320.50"
          }
        ]
      }
    ]
  }
}