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

List 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:

{
  "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.

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 for the distinct master-key and browser export requirements.