feat(trades): add token trades endpoint

[findolor]

Dependent PRs

• Depends on rainlanguage/raindex#2570 for SDK getTrades token filtering support. This PR should not merge until that raindex PR lands and the submodule pointer is mergeable.

Summary

• Adds GET /v1/trades/token/{address} for paginated trades involving a token address.
• Wires the new route through the existing TradesDataSource abstraction and the raindex SDK get_trades token filters.
• Reuses the shared trades list response shape used by owner-based trades, including pagination metadata and time filtering.
• Refactors the owner trades route to share pagination and trade mapping helpers with the new token route.
• Updates trade test mocks for the expanded TradesDataSource trait.
• Updates order type detection for the raindex parsed meta variant rename from DotrainGuiStateV1 to OrderBuilderStateV1.
• Bumps the rain.orderbook submodule to the SDK commit with token-filtered getTrades support.

Linear: RAI-526

Behavior

The new endpoint accepts the same pagination/time query parameters as GET /v1/trades/{address}:

GET /v1/trades/token/{tokenAddress}?page=1&pageSize=20&startTime=...&endTime=...

It returns trades where the token appears on either side of the trade by passing the token as both an input-token and output-token filter to the SDK.

Notes

• The current raindex local DB query path is still the baseline implementation. In local benchmarking, high-volume token queries are around four seconds for pageSize=50; materialized trade read tables should be handled as a separate SDK/local DB optimization.
• The unimplemented!() additions are test-only mock methods required by the expanded TradesDataSource trait; they are not production route code.

Verification

• nix develop -c cargo check
• nix develop -c cargo test
• nix develop -c cargo fmt
• nix develop -c rainix-rs-static

rainix-rs-static passes with pre-existing dead-code warnings in src/cache.rs.

Summary by CodeRabbit

• New Features

  • Added a new API endpoint to retrieve trades by token address with pagination support.

• Documentation

  • Updated OpenAPI documentation to include the new trades endpoint.

• Refactor

  • Refactored trade handlers to use shared helper functions for pagination and response construction.
  • Updated order type detection logic to use revised metadata structure.

• Chores

  • Updated rain.orderbook dependency to latest version.

[linear]

RAI-522

RAI-526

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a13dc35d-1b21-4ae9-8f79-853a638ef725

📥 Commits

Reviewing files that changed from the base of the PR and between 500f191 and 54e38c6.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (7)

• lib/rain.orderbook
• src/main.rs
• src/routes/order/get_order.rs
• src/routes/trades/get_by_address.rs
• src/routes/trades/get_by_token.rs
• src/routes/trades/get_by_tx.rs
• src/routes/trades/mod.rs

✅ Files skipped from review due to trivial changes (2)

• lib/rain.orderbook
• src/main.rs

🚧 Files skipped from review as they are similar to previous changes (5)

• src/routes/trades/get_by_tx.rs
• src/routes/order/get_order.rs
• src/routes/trades/get_by_address.rs
• src/routes/trades/mod.rs
• src/routes/trades/get_by_token.rs

---

📝 Walkthrough

Walkthrough

Adds GET /v1/trades/token/{address} with pagination and auth, extends TradesDataSource with token-based queries, refactors shared pagination/response helpers used by trades handlers, registers the new route in OpenAPI, updates test mocks, and changes DCA detection to use OrderBuilderStateV1 metadata.

Changes

Trades-by-Token Route

Layer / File(s)	Summary
TradesDataSource trait and Raindex implementation src/routes/trades/mod.rs	Adds get_trades_for_token and implements Raindex-backed token queries with GetTradesFilters and explicit page/page_size handling.
Pagination and response helpers src/routes/trades/mod.rs, src/routes/trades/get_by_address.rs	Adds trades_pagination_params and build_trades_list_response; refactors process_get_trades_by_address to use them and updates mocks in tests.
Trades-by-token route handler and tests src/routes/trades/get_by_token.rs	Adds GET /v1/trades/token/{address} Rocket handler, process_get_trades_by_token, Raindex wiring, and tests for success, empty results, upstream error, missing auth (401), and invalid address (422).
Integration and route registration src/main.rs, lib/rain.orderbook, src/routes/trades/get_by_tx.rs	Registers the new route in OpenAPI and Rocket routes(), updates rain.orderbook submodule SHA, and extends test mocks to satisfy the extended trait.

Order Type Classification

Layer / File(s)	Summary
DCA metadata detection update src/routes/order/get_order.rs	determine_order_type now matches ParsedMeta::OrderBuilderStateV1 and classifies OrderType::Dca when builder_state.selected_deployment contains "dca" (case-insensitive).

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant RocketHandler
  participant RaindexTradesDataSource
  participant RaindexClient
  Client->>RocketHandler: GET /v1/trades/token/{address} + Authorization + pagination
  RocketHandler->>RaindexTradesDataSource: get_trades_for_token(token, page, page_size, time_filter)
  RaindexTradesDataSource->>RaindexClient: query trades with GetTradesFilters + page/page_size
  RaindexClient-->>RaindexTradesDataSource: RaindexTradesListResult
  RaindexTradesDataSource-->>RocketHandler: mapped trades list
  RocketHandler-->>Client: 200 JSON (TradesByAddressResponse)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• ST0x-Technology/st0x.rest.api#50: Related changes extending TradesDataSource and trades endpoints wiring.
• ST0x-Technology/st0x.rest.api#51: Adds trade-listing infrastructure and pagination/response patterns that this PR builds on.
• ST0x-Technology/st0x.rest.api#35: Also modifies determine_order_type DCA detection logic in order detail flow.

Suggested reviewers

• JuaniRios
• 0xgleb
• hardyjosh

Poem

🐰 I hopped through trades and bound the page,
Token routes now listen, tests engage,
DCA reads builder-state anew,
Routes registered, docs updated too—hippity-hue!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 31.82% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(trades): add token trades endpoint' directly and clearly summarizes the main change: adding a new token trades API endpoint.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/rai-522-add-trades-token-endpoint

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[findolor]

• feat(trades): add batch order-hash query endpoint #107
• feat(trades): add taker trades endpoint #106
• feat(trades): add token trades endpoint #105 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add the label add-to-gt-merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/routes/order/get_order.rs (1)

70-83: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Add test coverage for DCA order type detection.

The DCA detection logic was modified but lacks test coverage. The only existing test (test_determine_order_type_solver_default) verifies the fallback case, not the new OrderBuilderStateV1 variant matching.

📝 Suggested test additions

Add tests to verify DCA detection with various deployment names:

#[rocket::async_test]
async fn test_determine_order_type_dca_lowercase() {
    let mut order = mock_order();
    // Add OrderBuilderStateV1 metadata with "dca" in selected_deployment
    // (This requires extending the mock to include parsed_meta)
    assert_eq!(determine_order_type(&order), OrderType::Dca);
}

#[rocket::async_test]
async fn test_determine_order_type_dca_uppercase() {
    let mut order = mock_order();
    // Add OrderBuilderStateV1 metadata with "DCA" in selected_deployment
    assert_eq!(determine_order_type(&order), OrderType::Dca);
}

#[rocket::async_test]
async fn test_determine_order_type_dca_mixed_case() {
    let mut order = mock_order();
    // Add OrderBuilderStateV1 metadata with "my-DCA-strategy" in selected_deployment
    assert_eq!(determine_order_type(&order), OrderType::Dca);
}

#[rocket::async_test]
async fn test_determine_order_type_non_dca() {
    let mut order = mock_order();
    // Add OrderBuilderStateV1 metadata with "limit-order" in selected_deployment
    assert_eq!(determine_order_type(&order), OrderType::Solver);
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/routes/order/get_order.rs` around lines 70 - 83, Add unit tests for
determine_order_type to cover the new OrderBuilderStateV1 branch: create mock
orders (using mock_order) whose parsed_meta() returns a
ParsedMeta::OrderBuilderStateV1 with builder_state.selected_deployment set to
values containing "dca" in lowercase, uppercase, and mixed case (e.g., "dca",
"DCA", "my-DCA-strategy") and assert determine_order_type(&order) ==
OrderType::Dca; also add a negative test where selected_deployment is
non‑matching (e.g., "limit-order") and assert OrderType::Solver. Ensure tests
reference determine_order_type, RaindexOrder, ParsedMeta::OrderBuilderStateV1,
and OrderType so they exercise the new detection logic.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@src/routes/order/get_order.rs`:
- Around line 70-83: Add unit tests for determine_order_type to cover the new
OrderBuilderStateV1 branch: create mock orders (using mock_order) whose
parsed_meta() returns a ParsedMeta::OrderBuilderStateV1 with
builder_state.selected_deployment set to values containing "dca" in lowercase,
uppercase, and mixed case (e.g., "dca", "DCA", "my-DCA-strategy") and assert
determine_order_type(&order) == OrderType::Dca; also add a negative test where
selected_deployment is non‑matching (e.g., "limit-order") and assert
OrderType::Solver. Ensure tests reference determine_order_type, RaindexOrder,
ParsedMeta::OrderBuilderStateV1, and OrderType so they exercise the new
detection logic.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6d605ad3-7b27-4b83-becc-fdfe7237c1af

📥 Commits

Reviewing files that changed from the base of the PR and between c0e9b91 and 500f191.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (7)

• lib/rain.orderbook
• src/main.rs
• src/routes/order/get_order.rs
• src/routes/trades/get_by_address.rs
• src/routes/trades/get_by_token.rs
• src/routes/trades/get_by_tx.rs
• src/routes/trades/mod.rs

[graphite-app]

Merge activity

• May 13, 5:09 PM UTC: findolor added this pull request to the Graphite merge queue.
• May 13, 5:31 PM UTC: Merged by the Graphite merge queue.