Wallet API
All paths are on the auth host. These routes use a Better Auth account session; do not substitute an OAuth bearer token without an explicitly supported route contract. The production session cookie normally has the name __Secure-better-auth.session_token, but applications should use the session API rather than manufacturing cookies.
Connect a wallet
POST /api/wallet/connect requires a session and an owned bapId. The BSV signed connection shape is:
{
"bapId": "owned-profile-id",
"authToken": "wallet-produced-bitcoin-auth-token",
"provider": "yours"
}Optional BSV fields include identityPubKey and paymentAddress. The response includes success, walletAddress, pubkey, provider, connectionMethod, and connectedAt. Use the wallet UI/client to obtain proof; never send its WIF.
The route also has EVM public-key/challenge and client-derived Type42 connection paths. Use their compatible UI rather than inventing derivation from public addresses. A connected EVM wallet does not imply ERC-20/ERC-721 ownership verification support. See wallet recovery boundaries.
Manage connections
| Endpoint | Input | Purpose |
|---|---|---|
GET /api/wallet/connect | Optional bapId query | List the user's profile connections |
DELETE /api/wallet/connect | bapId and address query | Remove an owned connection |
GET /api/wallet/address | Required bapId query | Primary/payment address and connection details |
POST /api/wallet/set-primary | { bapId, walletAddress } | Select a connected primary address |
POST /api/wallet/set-payment | { bapId, walletAddress } | Select a connected payment address |
Payment selection currently accepts only yours and 1sat provider connections and an optional depositAddress. It returns the selected paymentAddress and paymentProvider.
Disconnecting a wallet removes the association; it does not revoke the external key or move funds.
List NFTs
GET /api/wallet/nfts accepts optional refresh=true. It returns nfts, per-wallet results, and aggregate metadata. The current listing fetches only the first 100 indexer entries per address; it is not a complete paginated holdings export. Its profile lookup also differs from the ownership route, so do not use it as a cross-profile authorization source.
Verify ownership
POST /api/wallet/verify-ownership accepts either origin or collection, plus optional minCount (default 1). It resolves the session user's primary BAP profile and returns owns, count, and optional matching NFTs. It does not select a profile from the body.
Upstream indexer failures can produce an incomplete negative result. The response is unsigned JSON, not a portable proof. See NFT verification before making an access decision.