Add a `network` selector to the REST / GraphQL / WS API

[Miracle656]

Background

No route namespaces by network — /accounts, /summary/:address, /subscribe/:address, /graphql all hit the single global RPC/DB. Once storage and indexing are network-aware (W070–W072), the API must let callers pick a network (default testnet for back-compat).

What to build

Accept a network via ?network= (and/or a path segment) and thread it into RPC + DB reads.

Key files

• src/api.ts — routes (98-111, 157-763), getLatestLedger uses (189, 199, 227)
• GraphQL resolvers

Suggested execution

git checkout -b feat/api-network-selector

1. Parse network from query/header; validate against enabled networks; default testnet
2. Pass it to DB queries (W070) and getRpc(network) (W071)
3. Document the param in the OpenAPI spec

Acceptance criteria

• ?network=mainnet returns mainnet data; default stays testnet
• Invalid network → 400 with a clear message
• /readyz / /status report per-network health
• OpenAPI updated

Drips Wave · Complexity: Intermediate · 150 points

---

Required: Before submitting, join the contributor Telegram so your work can be tracked and counted toward the Stellar Wave: https://t.me/+fxHXq8f1SwlkZDBk

[barnabasolutayo-lgtm]

@barnabasolutayo-lgtm has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hello maintainer. I can resolve this issue quickly. Please assign to me. Thank you

ℹ️ Repo Maintainers: To accept this application, review their application or assign @barnabasolutayo-lgtm to this issue.

[femiolutayo]

@femiolutayo has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hello maintainer. I can resolve this issue quickly. Please assign to me. Thank you

ℹ️ Repo Maintainers: To accept this application, review their application or assign @femiolutayo to this issue.

[collinsezedike]

@collinsezedike has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I've built multi-network API selectors before, and the WebSocket case is the one that needs extra care since a subscription's network context has to persist for the connection's lifetime, not just get read once at connect time.

Here's my plan:

• Parse network from the query string (and/or a header), validate against the enabled network list, defaulting to testnet for back-compat
• Thread the resolved network through every DB query and getRpc(network) call across src/api.ts (routes 98-111, 157-763) and the GraphQL resolvers
• For /subscribe/:address specifically, bind the network to the WS connection at handshake time rather than re-reading it per message, so a long-lived subscription stays consistent even if a client later sends requests with a different query param
• Return 400 with a clear message on an invalid/unrecognized network value
• Update /readyz and /status to report health per-network rather than a single global status
• Update the OpenAPI spec to document the new parameter

This depends on W070-W072 landing for network-aware storage and indexing, so I'd confirm their status with you before starting. Happy to start once confirmed and I'm assigned.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @collinsezedike to this issue.

[Glorious21]

@Glorious21 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I like that this issue sits right at the seam between infrastructure and API design once storage and indexing become network-aware (W070–W072), the API is the last mile that actually exposes that to callers. Getting the network selector right (clean validation, sane defaults, no breaking changes for existing testnet callers) is the kind of "boring but critical" work that determines whether the rest of the network-awareness effort is actually usable. I've worked with Stellar/Soroban and similar blockchain RPC-backed APIs before, so I understand why per-network RPC/DB routing and health reporting (/readyz, /status) matter here a wrong or silently-defaulted network on a financial/indexing system is a real correctness bug, not just a UX nit. I'd like to take this on end-to-end: query/header parsing, threading the selection through to getRpc(network) and the DB layer, and keeping the OpenAPI spec honest about the new parameter.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Glorious21 to this issue.

[royalTreasure]

@royalTreasure has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi, I would like to work on this issue. I will add network parsing from the query string or header across all routes in api.ts and the GraphQL resolvers, validating the value against the set of enabled networks and defaulting to testnet for backwards compatibility so existing callers are not broken. I will thread the resolved network into both the DB queries and the getRpc(network) factory from the W071 refactor so every read is correctly scoped to the requested network, and return a clear 400 response with a descriptive message when an invalid network value is supplied. I will also update the /readyz and /status endpoints to report per-network health and document the network parameter in the OpenAPI spec so the API surface is fully described before submitting. Can I be assigned?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @royalTreasure to this issue.

[drips-wave]

Congratulations, @royalTreasure! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @royalTreasure: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊