/v2 for every read in a new REST integration. Existing clients can migrate incrementally. Use the v2 directory for identity lookup and the activity collection for position-count selection. The existing /v1/traders endpoint and list_traders tool remain available with their original fields, defaults, and permissions. No retirement date is set.
Import /v2/openapi.json for the complete v2 contract. /v1/openapi.json describes v1, and /openapi.json remains a v1 alias for existing imports. The documentation offers both versions and opens v2 by default. MCP keeps /mcp and the existing names of unchanged tools.
Choose the replacement
The directory accepts
search, traderIds, sourcePlatforms, limit, and cursor. It returns identity fields and one nullable source, with no tradeCount. Each trader has at most one assigned source. A null source means no assignment; selecting that trader’s messages returns no rows.
The activity collection accepts the legacy analytical filters, renaming minTrades to minPositionCount. It returns { traderId, positionCount } rows plus filtersApplied. Counts retain the legacy eligible-position rules, inclusive position-open bounds, default minimum of three, and alphabetical pagination. With no dates, counts cover all eligible history. minPositionCount=0 includes zero-position traders unless an asset filter requires a matching position. An explicit trader ID does not bypass visibility or the count threshold.
Permissions and visibility
Identity discovery requiresdirectory.read and either message or signal visibility for the caller’s role. It requires no positions, messages, or assigned source. Directory access does not grant message or trading-data access. Both-hidden traders remain hidden even when a generated summary references their ID.
Activity requires stats.read and signal visibility. A legacy directory-only client must obtain a stats grant before migrating analytical queries. Existing grants are not changed automatically.
Messages use message visibility, regardless of signal visibility. Resolve all matching directory candidates before selecting a trader. Do not guess between similarly named accounts. Message rows retain their existing data and add traderId; existing message IDs, filters, and cursors continue to work.
Migrate a client
- Confirm the new endpoints or MCP tools are available in the target environment.
- Move identity searches and ID hydration to the new directory. Remove analytical filters and any dependency on
tradeCountfrom these requests. - Move position-count queries to the activity collection, rename the count filter and field, and resolve returned trader IDs through the directory when needed.
- Restart pagination when replacing legacy trader discovery with the new directory or activity collection. Their cursors cannot be transferred between these collections. For unchanged reads, keep existing pagination and feed continuation tokens when switching between v1 and v2, using the same query and environment.
- Verify permissions and expected results before removing the client’s legacy calls.