# Wallet tracking

Track public addresses to follow their activity. Tracking an address does not import its keys, create a custody wallet, or grant authority to spend its assets.

## Manage tracked wallets

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/wallet-trackers` | List trackers with optional `search`, `limit`, and `cursor` |
| `POST` | `/v1/wallet-trackers` | Add an address with a label and optional emoji and sound |
| `PATCH` | `/v1/wallet-trackers/:trackerId` | Update a tracker |
| `DELETE` | `/v1/wallet-trackers/:trackerId` | Remove a tracker |
| `DELETE` | `/v1/wallet-trackers` | Remove every tracker on the account |
| `PATCH` | `/v1/wallet-trackers/settings` | Change account event filters |
| `POST` | `/v1/wallet-trackers/import` | Import an atomic list of addresses |
| `GET` | `/v1/wallet-trackers/export` | Export the portable tracker list and settings |

Tracker operations accept a master key. Browser mutations require CSRF protection. They do not require the financial API's idempotency header. The backend owns the 10,000-wallet account quota.

## Import a portable list

The app accepts one CSV, TXT, or JSON file and detects JSON from its contents, including JSON exports with a `.txt` suffix. API clients parse the file first and send one JSON request with an `items` array. Each item uses `address` and `name`; the single-tracker create endpoint uses `label` instead of `name`.

~~~bash POST /v1/wallet-trackers/import
curl https://starswap.cc/api/v1/wallet-trackers/import \
  -X POST \
  -H "Authorization: Bearer $STARSWAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"address":"0x7A18d4F951B0134436A1b17854F171Aa05E0F32b","name":"Example wallet"}]}'
~~~

Send up to 10,000 entries in one request. Addresses are normalized by network family and duplicates are reconciled. The backend commits the entire import or rolls it back if validation or the resulting account quota fails. Keep the import atomic instead of splitting it into smaller writes.

The response reports `received`, `imported`, `alreadyTracked`, `updated`, and `repeatedInFile`, plus settings-related results. Optional legacy file settings may be ignored; inspect `ignoredSettings` and `legacyEventFilterRows`.

## Read activity

`GET /v1/wallet-trackers/feed` returns the account feed, revision, tracked-wallet count, and pending-wallet count. `GET /v1/wallet-trackers/market?chain=CHAIN&token=TOKEN` returns activity for an exact market. These are live tracking views, not a promise of complete historical backfill.

The app subscribes to `/v1/wallet-trackers/feed/stream` for live updates. Stream consumers should distinguish the initial snapshot from new events. Keep notifications and sounds opt-in, and do not replay them for the initial snapshot.