Get Your Stellar Wallet Asset Balances

The wallet overview endpoint gives you a complete snapshot of your Pay3 wallet. It returns your Stellar account’s on-chain asset balances — including native XLM and any issued assets such as USDC — fetched live from the Stellar network, along with a summary of the smart accounts you have linked to this wallet. Use it to power dashboards, balance displays, or pre-flight checks before initiating payments.

Endpoint

GET /api/wallet/overview Authentication is required. Include either the pay3_session cookie or an Authorization: Bearer <session-token> header.

Response

All Pay3 API responses are wrapped in a standard envelope:

{
  "data": { ... },
  "requestId": "req_01hx2q3r4s5t6u7v8w9x0y1z"
}

A successful 200 OK response returns your wallet metadata, live balances, and linked smart accounts inside data.

object

The wallet overview payload.

Hide data fields

object

Metadata about your Pay3 wallet record.

Show wallet fields

string

Pay3 internal wallet record ID.

string

Your Stellar public key (G...).

string

The Stellar network — TESTNET or PUBLIC.

boolean

Whether this is your primary wallet for the authenticated user account.

array

An array of asset balance objects fetched live from Stellar Horizon.

Show balance item fields

string

The asset identifier. For native lumens this is "XLM". For issued assets this is "<CODE>:<ISSUER_ADDRESS>" — for example, "USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5".

string

The current balance as a decimal string (e.g., "100.0000000"). Stellar balances have 7 decimal places of precision.

array

Smart account contracts linked to this wallet. See GET /api/smart-accounts for full detail on each account.

Show smart account item fields

string

Pay3 internal smart account record ID.

string

The Soroban contract address (C...).

string

Network the contract is deployed on — TESTNET or PUBLIC.

string

ISO 8601 timestamp of when this smart account was linked.

string

A unique identifier for this API request, useful for support and debugging.

Balances are fetched live from the Stellar Horizon API on every request. In high-frequency scenarios, consider caching the response client-side for a few seconds to avoid rate-limiting on the Stellar network.

Example

Request

curl --request GET \
  --url https://api.pay3.dev/api/wallet/overview \
  --header 'Authorization: Bearer your-session-token-here'

Response Body

{
  "data": {
    "wallet": {
      "id": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
      "publicAddress": "GAHJJJKMOKYE4RVPZEWZTKH5FVI4PA3VL7GK2LFNUBSGBV8XVMHXV6R",
      "network": "TESTNET",
      "isPrimary": true
    },
    "balances": [
      {
        "asset": "XLM",
        "balance": "9872.3401200"
      },
      {
        "asset": "USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
        "balance": "250.0000000"
      }
    ],
    "smartAccounts": [
      {
        "id": "e7f8a9b0-c1d2-3456-7890-abcdef123456",
        "contractId": "CDJT5OQNBBSXMFBKXH3ZHQJH3XPXKBQQMYIBNHQK5ZYXDV7KXQHRMTE",
        "network": "TESTNET",
        "createdAt": "2024-11-01T10:30:00.000Z"
      }
    ]
  },
  "requestId": "req_01hx2q3r4s5t6u7v8w9x0y1z"
}

Error Responses

HTTP Status	Description
`401 Unauthorized`	Missing or invalid session.
`404 Not Found`	No wallet record found for the authenticated user.
`502 Bad Gateway`	Stellar Horizon returned an error fetching live balances.

Authentication

Wallet & Accounts

Sessions & Policies

Transactions

Contacts & Analytics

Get Your Stellar Wallet Asset Balances — Pay3 Wallet

Endpoint

Response

Example

Request

Response Body

Error Responses

​Endpoint

​Response

​Example

​Request

​Response Body

​Error Responses

Endpoint

Response

Example

Request

Response Body

Error Responses