docs: cover sdk wallet position helpers

Author: ayazabbas

docs/sdk/examples.md

@@ -58,6 +58,39 @@ async fn main() -> Result<()> {
 
 **What it demonstrates:** [Client setup](client.md) in read-only mode, [indexer queries](indexer.md), on-chain market reads.
 
+## redeem_backlog_check — Find Redeemable Positions Before Redemption
+
+This is the concise discovery flow for redemption bots:
+
+1. query the indexer backlog with `get_redeemable_positions(address)`
+2. pull the factory market ID from each normalized entry
+3. pass that factory market ID into on-chain redemption
+
+```rust
+use strike_sdk::prelude::*;
+
+let address = "0x...";
+let redeemable = client.indexer().get_redeemable_positions(address).await?;
+
+for pos in redeemable {
+    let Some(factory_market_id) = pos.factory_market_id() else {
+        continue;
+    };
+
+    println!(
+        "redeem backlog | factory {} | lots {:?} | redeemable {:?}",
+        factory_market_id,
+        pos.lots_hint(),
+        pos.redeemable()
+    );
+
+    // Example on-chain call path once you choose an amount:
+    // client.redeem().redeem(factory_market_id, amount).await?;
+}
+```
+
+The SDK normalizes legacy and v1 redeemable payload variants here, so `factory_market_id()` and related accessors remain the stable interface.
+
 ## place_orders — Full Trading Lifecycle
 
 Connects with a wallet, approves USDT, finds an active market, places a bid and ask, then cancels both.

docs/sdk/indexer.md

@@ -8,6 +8,8 @@ All indexer endpoints are available under the `/v1/` prefix. The legacy unprefix
 
 Responses use a standard envelope: `{ data: [...], meta: { total, limit, offset } }`. The SDK handles this transparently — callers receive plain `Vec<Market>`, `Vec<IndexerOrder>`, etc. with no change to existing code.
 
+For wallet position endpoints, the SDK also normalizes known schema drift across legacy and v1 payloads. Filled and redeemable entries preserve the raw JSON but expose stable accessors like `factory_market_id()`, `orderbook_market_id()`, `redeemable()`, `resolved()`, and `lots_hint()`.
+
 ## Canonical OpenAPI Reference
 
 The generated OpenAPI spec is the source of truth for the public indexer API:
@@ -143,6 +145,60 @@ The v1 response from `/v1/positions/:address` is paginated:
 
 The SDK handles both the v1 paginated and legacy flat-array formats automatically — `get_open_orders` always returns `Vec<IndexerOrder>`.
 
+## Get Wallet Positions
+
+Fetch the full wallet snapshot from `/positions/:address`:
+
+```rust
+let address = "0x...";
+let positions = client.indexer().get_positions(address).await?;
+
+println!("open orders: {}", positions.open_orders.len());
+println!("filled positions: {}", positions.filled_positions.len());
+
+for pos in &positions.filled_positions {
+    println!(
+        "factory {:?} | orderbook {:?} | lots {:?} | redeemable {:?}",
+        pos.factory_market_id(),
+        pos.orderbook_market_id(),
+        pos.lots_hint(),
+        pos.redeemable()
+    );
+}
+```
+
+`get_positions()` returns:
+
+```rust
+pub struct IndexerPositions {
+    pub open_orders: Vec<IndexerOrder>,
+    pub filled_positions: Vec<IndexerFilledPosition>,
+}
+```
+
+Use the accessor methods on `IndexerFilledPosition` instead of relying on a specific upstream JSON shape.
+
+## Get Redeemable Positions
+
+Fetch the wallet's redeem backlog from `/positions/:address/redeemable`:
+
+```rust
+let address = "0x...";
+let redeemable = client.indexer().get_redeemable_positions(address).await?;
+
+for pos in &redeemable {
+    if let Some(factory_market_id) = pos.factory_market_id() {
+        println!(
+            "redeem backlog | factory {} | lots {:?}",
+            factory_market_id,
+            pos.lots_hint()
+        );
+    }
+}
+```
+
+This is the right discovery path before calling on-chain redemption. The SDK normalizes both paginated and legacy redeemable payloads, including nested and casing-drifted field names.
+
 ### IndexerOrder Type
 
 ```rust

docs/sdk/overview.md

@@ -4,7 +4,7 @@ The Strike SDK is a Rust crate for programmatic trading on Strike prediction mar
 
 ## Design Philosophy
 
-The SDK is **on-chain first**. All trading operations go directly to BNB Chain via RPC. Live data (events, balances, market state) comes from a WSS subscription or RPC reads. The [indexer](indexer.md) is available for startup snapshots (fetching all markets, orderbook state), but is never in the critical trading path.
+The SDK is **on-chain first**. All trading operations go directly to BNB Chain via RPC. Live data (events, balances, market state) comes from a WSS subscription or RPC reads. The [indexer](indexer.md) is available for startup snapshots (fetching all markets, orderbook state, wallet positions, redeem backlog), but is never in the critical trading path.
 
 ## Features
 
@@ -13,9 +13,12 @@ The SDK is **on-chain first**. All trading operations go directly to BNB Chain v
 | Order management | Place, cancel, and replace orders in batch transactions |
 | Event streaming | Real-time WSS subscriptions with auto-reconnect |
 | Vault & tokens | USDT approval, balance queries, outcome token / position operations |
-| Indexer client | REST client for market snapshots and orderbook state |
+| On-chain market reads | Market counts/IDs plus `market_meta(factory_market_id)` for factory-to-orderbook metadata |
+| Indexer client | REST client for market snapshots, wallet positions, redeem backlog, and orderbook state |
 | Nonce manager | Optional `nonce-manager` feature flag for bots sending rapid transactions |
 
+Wallet position helpers normalize known schema drift in filled-position and redeemable payloads, so integrations can use stable accessors instead of decoding multiple indexer variants themselves.
+
 ## Preset Configs
 
 Use `StrikeConfig::bsc_mainnet()` for BSC mainnet with default RPC, WSS, and indexer endpoints. See [Client Configuration](client.md) for custom setups.

sdk/rust/README.md

@@ -34,6 +34,17 @@ async fn main() -> Result<()> {
     let count = client.markets().active_market_count().await?;
     println!("{count} active markets on-chain");
 
+    if let Some(first) = markets.first() {
+        let meta = client
+            .markets()
+            .market_meta(first.factory_market_id as u64)
+            .await?;
+        println!(
+            "factory {} -> orderbook {} | internal positions: {}",
+            meta.factory_market_id, meta.orderbook_market_id, meta.use_internal_positions
+        );
+    }
+
     Ok(())
 }
 ```
@@ -181,12 +192,39 @@ strike-sdk = { version = "0.2", default-features = false }
 | `chain::vault` | USDT approval, balance queries |
 | `chain::redeem` | Outcome token redemption |
 | `chain::tokens` | ERC-1155 outcome token helpers |
-| `chain::markets` | On-chain market state reads |
+| `chain::markets` | On-chain market state reads, including `market_meta(factory_market_id)` |
 | `events::subscribe` | WSS event stream with auto-reconnect |
 | `events::scan` | Historical event scanning (chunked getLogs) |
 | `indexer` | REST client: markets, positions, trades, stats (API v1) |
 | `nonce` | `NonceSender` for sequential TX sends |
 
+## Wallet Positions
+
+Use the indexer for wallet snapshots and redeem backlog discovery:
+
+```rust
+let wallet = "0x...";
+
+let positions = client.indexer().get_positions(wallet).await?;
+println!(
+    "open orders: {} | filled positions: {}",
+    positions.open_orders.len(),
+    positions.filled_positions.len()
+);
+
+let redeemable = client.indexer().get_redeemable_positions(wallet).await?;
+for entry in &redeemable {
+    println!(
+        "factory {:?} | lots {:?} | redeemable {:?}",
+        entry.factory_market_id(),
+        entry.lots_hint(),
+        entry.redeemable()
+    );
+}
+```
+
+The SDK normalizes evolving `/positions/:address` and `/positions/:address/redeemable` payloads into accessor-based position types, so callers do not need to chase field-name drift across indexer versions.
+
 ## AI Markets
 
 Markets with `is_ai_market: true` are resolved by the Flap AI Oracle instead of Pyth price feeds. The `Market` struct includes: