# Wallets

Each account has a main wallet and can create independent subwallets. A wallet has its own settlement balance, an address for each supported network family, portfolio positions, trades, and recovery material. Solana addresses are case-sensitive and must be stored exactly as returned.

## Endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/wallets` | List account wallets |
| `POST` | `/v1/wallets` | Create a subwallet |
| `GET` | `/v1/wallets/:walletId` | Read one wallet |
| `PATCH` | `/v1/wallets/:walletId` | Rename a wallet |
| `POST` | `/v1/wallets/:walletId/archive` | Archive an empty subwallet |
| `POST` | `/v1/wallets/:walletId/restore` | Restore an archived subwallet |
| `GET` | `/v1/wallets/:walletId/portfolio` | Read holdings for one network |
| `GET` | `/v1/wallets/:walletId/portfolios` | Read holdings across networks |
| `POST` | `/v1/wallet-portfolios/batch` | Read holdings for multiple owned wallets |
| `GET` | `/v1/wallets/:walletId/portfolio-history` | Read account-value history for one wallet |
| `POST` | `/v1/wallets/:walletId/export` | Export recovery material |
| `POST` | `/v1/wallets/import` | Import a wallet through a browser session |
| `POST` | `/v1/wallets/export-all` | Export all wallets through a browser session and email code |

## List wallets

~~~bash GET /v1/wallets
curl "https://starswap.cc/api/v1/wallets?limit=50" \
  -H "Authorization: Bearer $STARSWAP_API_KEY"
~~~

Collection responses may include `nextCursor`. Pass it as the next request's `cursor` query parameter.

Each wallet returns an `addresses` array:

~~~json
{
  "addresses": [
    { "family": "evm", "address": "0x7A18d4F951B0134436A1b17854F171Aa05E0F32b" },
    { "family": "solana", "address": "HAgk14JpMQLgt6rVgv7cBQFJWFto5Dqxi472uT3DKpqk" }
  ]
}
~~~

Select the address whose `family` matches the `family` returned for a network by `GET /v1/chains`. Portfolio responses include the selected chain address as `{ family, address }`.

## Read holdings

Pass `chain` to the single-network portfolio endpoint. Add `token` to read one exact position instead of relying on a cached whole-wallet snapshot.

~~~bash GET /v1/wallets/:walletId/portfolio
curl 'https://starswap.cc/api/v1/wallets/wlt_example/portfolio?chain=solana&token=solana%3Anative' \
  -H "Authorization: Bearer $STARSWAP_API_KEY"
~~~

The response separates `canonicalBalanceRaw`, an onchain settlement-token balance, from provider portfolio positions. A missing provider result or `rpcError` means the read is unavailable, not that the wallet has zero assets. Positions use `balanceRaw` with their own `decimals`. Native SOL also exposes `withdrawableRaw` after leaving the current rent-exempt reserve.

`GET /v1/wallets/:walletId/portfolios` accepts optional `chain` or `family` filters. `POST /v1/wallet-portfolios/batch` is a read operation with a JSON body containing `walletIds` and optional `chain` and `token`. It accepts up to 100 unique wallets for full portfolios, or 1,000 for a token-scoped read with both `chain` and `token`. Inspect each returned item's `error` independently.

## Balances and PnL

The wallet's `balance` contains `availableMicros`, `reservedMicros`, `gasReservedMicros`, and `pendingSettlementMicros`. Only `availableMicros` is spendable. Pending settlement includes confirmed EVM sell deposits that are waiting for finality. Moving those funds to available balance does not increase account value again.

Confirmed sell `pnlUSD` already includes trading fees and actual gas. Do not subtract gas a second time. Open-position PnL and `averageBuyPriceUSD` are omitted when relevant StarSwap history exists but the remaining cost basis cannot be verified against the held quantity. Treat missing values as unavailable. Average entry excludes buy gas; cost basis includes it.

For historical values, pass `range=day`, `week`, `month`, or `all` to the portfolio-history endpoint. The default is `week`. A change in account value includes deposits and withdrawals and is not realized trading PnL.

## Archive safely

Move settlement balance and onchain assets out of a subwallet and resolve pending operations before archiving it. The main wallet cannot be archived. Wallet export returns `Cache-Control: no-store`. Exported keys use `{ family, encoding, value }`, with `hex` for EVM and `base58` for Solana. See [Authentication](/docs/authentication) for the distinct master-key and browser export requirements.