Update cards, accounts and users documentation

[ricardobcl]

Description

Fixes drift between the Cards, Accounts and Users pages and the current API behavior, verified against uphold/backend master.

_cards.md

• Cards are not "automatically provisioned" addresses — they are created on demand via the Create Card Address endpoint.
• Replaced the stale Create Card Address network list (which still included the long-removed interledger): valid values are the networks of the cryptocurrencies available to the user; current examples given instead of a fixed list.
• The tag property applies to all tag-based networks — stellar, ton and xrp-ledger — not just the XRP Ledger.
• settings.position is a deprecated no-op: it is silently ignored on update and always returned as 0; examples and the Update Card table now reflect this.
• Get Card: :id resolves by card ID or any of the card's crypto addresses (any network), not just "its bitcoin address".
• Create Card: parameters table now marks currency as required and label as optional (with the default label behavior), and documents settings.starred.
• Create Card Address: documented the preconditions (deposits capability → 403, currency must support buying → 400, one address per network per card).
• List Cards: documented the id: filter and the sort/direction/normalizedCurrency query parameters.
• List Card Addresses: the bitcoin sample now shows wrappedSegWit/nativeSegWit formats (legacy pubkeyhash entries are filtered out for bitcoin/litecoin).
• Fixed a broken multi-line curl example (missing \ continuation).

_accounts.md

• The account-type story now matches reality: bank accounts surface their network as type (fps, swift and wire can appear alongside ach/sepa), and exchange accounts exist; the deposits/withdrawals table is scoped to the common types. The card row's "Withdrawals: No" now carries a footnote pointing at OCT push-to-card settlement, resolving an internal contradiction with the Approved cards table.
• List Accounts: documented the actual filter values (status: expired/failed/ok/pending — with ok as the unstated default; type: bank/card/exchange plus deprecated ach/fps/sepa) and that swift/wire appear in responses but are not filterable.
• Response examples now include the always-present provider and the type-specific fields (bic/iban for sepa, masked numbers for ach, cardNumberMasked/expiryDate for card).
• Typo fixes ("successfull" ×3) and a broken table row.

_users.md

• GET /me/phones: the example paired a Bearer request with the response shape that is only returned for email/password authentication. OAuth requests actually receive unmasked {country, e164, id} items — both shapes are now documented, and the phones:read scope aside was added.
• GET /me example: added missing private-response fields (id, fullName, identityCountry, type, balances.available/pending, per-currency available).
• The cards property "will be removed" → has been removed; dropped the obsolete large-payload warning.
• Fixed booleans documented as strings.

Notes for reviewers

• No new endpoints were documented. Found but deliberately left undocumented (flagging in case any should be added): DELETE /v0/me/accounts/:id, PATCH /v0/me/accounts/:id (label), PATCH /v0/me, GET /v0/me/features, POST /v0/me/cards/:card/addresses/:address/sign (feature-gated), DELETE /v0/me/phones/:phone.
• The deposits/withdrawals support matrix values for the newer account types were not asserted — enforcement lives across transaction validators and gateways, so the table is scoped to the types it was originally written for.

Related issues

Follow-up to #250 (documentation audit against uphold/backend master).

Impacted areas

Cards, Accounts and Users pages of the API reference.

Steps to reproduce or test

Development

Every claim was traced to the enforcing code in uphold/backend master (card/account/user-phone controllers, managers, model masks and their tests).

QA

Render the three pages; optionally verify GET /me/phones with a Bearer token returns unmasked numbers and that creating a card address on an unsupported network is rejected.

Checklist

• Add label Breaking Change if it applies.
• Commits are atomic and logically separated.
• Performance implications have been considered.
• Security implications have been considered.
• API documentation, if required, has been created or updated.
• New dependencies have been added to package.json.
• The README file, if required, has been updated.
• Architectural diagram, if required, has been updated.

Deploy notes

N/A — no files added or removed, so no slate index changes are needed.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates the API reference documentation for Cards, Accounts, and Users to match current API behavior (as verified against uphold/backend master), removing outdated statements and aligning examples/parameter descriptions with what the endpoints actually return/accept.

Changes:

• Updated Cards docs to reflect on-demand address creation, expanded filtering/sorting docs, clarified :id resolution, and documented tag-based networks and settings.position deprecation behavior.
• Updated Accounts docs to reflect current account types/filters and response fields, and corrected table/content typos.
• Updated Users docs to correct /me and /me/phones response examples/behavior (including OAuth vs email/password shapes) and removed obsolete guidance.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
_cards.md	Aligns Cards endpoint descriptions, parameters, and examples with current address creation, filtering/sorting, and response behavior.
_accounts.md	Updates account type narrative/filters and response examples to match current API output; fixes table/typos.
_users.md	Corrects /me and /me/phones documentation and examples, including auth-dependent response shapes and removed fields.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.