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.

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.