> ## Documentation Index
> Fetch the complete documentation index at: https://pay3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Your Stellar Wallet Asset Balances — Pay3 Wallet

> Retrieve your Stellar wallet metadata, live asset balances, and linked smart accounts in a single call. Ideal for dashboards and pre-payment checks.

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:

```json theme={null}
{
  "data": { ... },
  "requestId": "req_01hx2q3r4s5t6u7v8w9x0y1z"
}
```

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

**data** `object`

The wallet overview payload.

**data fields**

**data.wallet** `object`

Metadata about your Pay3 wallet record.

**wallet fields**

**data.wallet.id** `string`

Pay3 internal wallet record ID.

**data.wallet.publicAddress** `string`

Your Stellar public key (`G...`).

**data.wallet.network** `string`

The Stellar network — `TESTNET` or `PUBLIC`.

**data.wallet.isPrimary** `boolean`

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

**data.balances** `array`

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

**balance item fields**

**data.balances\[].asset** `string`

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

**data.balances\[].balance** `string`

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

**data.smartAccounts** `array`

Smart account contracts linked to this wallet. See
[`GET /api/smart-accounts`](https://pay3.mintlify.site/api-reference/smart-accounts/list) for full
detail on each account.

**smart account item fields**

**data.smartAccounts\[].id** `string`

Pay3 internal smart account record ID.

**data.smartAccounts\[].contractId** `string`

The Soroban contract address (`C...`).

**data.smartAccounts\[].network** `string`

Network the contract is deployed on — `TESTNET` or `PUBLIC`.

**data.smartAccounts\[].createdAt** `string`

ISO 8601 timestamp of when this smart account was linked.

**requestId** `string`

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

> [!NOTE]
>
> 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

```bash theme={null}
curl --request GET \
  --url https://api.pay3.dev/api/wallet/overview \
  --header 'Authorization: Bearer your-session-token-here'
```

### Response Body

```json theme={null}
{
  "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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.