feat: remove all direct RPC calls, route through Turbine API (#30)

* feat: remove all direct RPC calls, route through Turbine API

Eliminates the SDK's dependency on direct blockchain RPC connections.
All on-chain queries now route through the Turbine API.

Changes:
- _get_contract_nonce() → GET /contracts/nonce/:contract/:owner
- get_usdc_balance() → GET /users/:address/balances
- get_usdc_allowance() → GET /users/:address/balances
- approve_usdc() → gasless permit via POST /relayer/usdc-permit
- claim_winnings() → GET /users/:address/claim-data + sign + POST /relayer/ctf-redemption
- batch_claim_winnings() → same pattern, batched
- discover_positions() → GET /users/:address/claimable (replaces Multicall3)
- Removed hardcoded Ankr RPC key from discovery.py
- Removed web3 from required dependencies

All method signatures remain backward compatible. The SDK no longer
requires any RPC URL or web3 connection.

Requires: ojo-network/turbine-clob#241 (new API endpoints)

* docs: update all docs to reflect API-only SDK (no RPC/web3)

- CLAUDE.md: added API-only description, updated approve_usdc to return dict,
  updated Gasless concept, added API routing details under the hood
- create-bot/SKILL.md: updated gasless approval pattern
- create-liquidity-bot/SKILL.md: updated gasless approval pattern
- setup/SKILL.md: noted API-only in env var description
- README.md: added API-only overview, no RPC note in credentials
- docs/onboarding.md: reinforced no RPC/web3 needed

Author: ten-nex

.claude/skills/create-bot/SKILL.md

@@ -364,7 +364,7 @@ After the bot is running, suggest next steps based on the user's goals (from `us
 
 1. **Order verification chain:** After `post_order()`, sleep 2 seconds, then check failed trades → pending trades → recent trades → open orders. This sequence ensures the bot knows the true state of its order. Skipping steps causes phantom orders or missed fills.
 
-2. **Gasless USDC approval:** One-time max EIP-2612 permit per settlement contract. Check allowance first, skip if already approved. Never do per-order approvals.
+2. **Gasless USDC approval:** One-time gasless permit via API per settlement contract. `approve_usdc()` returns a dict with `tx_hash` key (not a raw tx hash string). Check allowance first via API, skip if already approved. Never do per-order approvals. No web3 or RPC needed.
 
 3. **Market transitions:** Poll every 5 seconds for new markets. On transition: cancel all orders on the old market, reset state (pending orders, processed trade IDs, expiration flag), approve USDC for the new settlement if needed, then resume trading.
 

.claude/skills/create-liquidity-bot/SKILL.md

@@ -329,7 +329,7 @@ After the bot is running, suggest next steps based on the user's goals:
 
 **DO NOT modify these when generating bots.** They exist in `examples/market_maker.py` for a reason and must be preserved exactly:
 
-1. **Gasless USDC approval:** One-time max EIP-2612 permit per settlement contract. Check allowance first, skip if already approved. Never do per-order approvals.
+1. **Gasless USDC approval:** One-time gasless permit via API per settlement contract. `approve_usdc()` returns a dict with `tx_hash` key (not a raw tx hash string). Check allowance first via API, skip if already approved. Never do per-order approvals. No web3 or RPC needed.
 
 2. **Graceful rebalance:** Place new orders FIRST, brief pause, then cancel old ones. This ensures continuous liquidity — no gap where traders can't trade. This is critical and different from cancel-then-place.
 

.claude/skills/setup/SKILL.md

@@ -228,7 +228,7 @@ TURBINE_HOST=https://api.turbinefi.com
 - `TURBINE_PRIVATE_KEY` — Their wallet's signing key. Never leaves this machine.
 - `TURBINE_API_KEY_ID` / `TURBINE_API_PRIVATE_KEY` — Left blank intentionally. The bot auto-registers API credentials on first run and saves them back to this file.
 - `CHAIN_ID=137` — Polygon mainnet. This is where Turbine's active markets are.
-- `TURBINE_HOST` — Turbine's API endpoint.
+- `TURBINE_HOST` — Turbine's API endpoint. All SDK operations (approvals, claims, balance checks) route through this — no RPC URL or web3 needed.
 
 ---
 

CLAUDE.md

@@ -47,6 +47,8 @@ This matters because it dramatically lowers the barrier to entry. A new user doe
 
 Turbine runs an off-chain orderbook (CLOB) with on-chain settlement. Orders are signed off-chain using EIP-712, matched by Turbine's API, then settled on-chain via modified Gnosis CTF smart contracts. Market resolution is handled by the UMA Optimistic Oracle — after 15 minutes, the oracle checks BTC's price against the strike and declares a winner. The 1% flat fee per trade is the only cost.
 
+**From the SDK's perspective**, everything goes through the Turbine API — there are no direct RPC or on-chain calls. USDC approvals use gasless permits via `/relayer/usdc-permit`, balance/allowance checks go through `/users/:address/balances`, claims go through `/users/:address/claim-data` + the relayer, and contract nonces come from `/contracts/nonce/:contract/:owner`.
+
 ### Competitions and Hackathons
 
 Turbine is actively growing its user base through two channels:
@@ -61,6 +63,8 @@ Turbine is actively growing its user base through two channels:
 
 This is the official Python SDK for Turbine's API, bundled with example trading bots and Claude Code skills for bot generation. It exists to get people trading on Turbine as fast as possible.
 
+**The SDK is fully API-routed** — all operations go through `api.turbinefi.com`. There is no RPC URL, no web3 dependency, and no direct blockchain node access required. Users only need a private key, chain ID, and the API host.
+
 **Why it exists:** Turbine is a prediction markets platform, but a platform without traders is empty. This repo is the primary onboarding funnel — it's how new users go from "curious" to "actively trading." The easier it is to clone this repo, build a bot, and start competing, the more traders Turbine gets.
 
 The typical user journey:
@@ -213,7 +217,7 @@ When a user wants to create or modify a bot:
 
 4. **Preserve critical infrastructure patterns.** These exist in every working bot and must not be removed or altered:
    - **Order verification chain:** After submitting an order, wait 2 seconds, then check failed trades → pending trades → recent trades → open orders. This sequence ensures the bot knows the true state of its order.
-   - **Gasless USDC approval:** One-time max EIP-2612 permit per settlement contract. Check allowance first, skip if already approved.
+   - **Gasless USDC approval:** One-time gasless permit via API per settlement contract. `approve_usdc()` returns a dict with `tx_hash` (not a raw tx hash string). Check allowance first via API, skip if already approved.
    - **Market transitions:** Poll for new markets every 5 seconds. When a new market appears, cancel all orders on the old market, reset state, and start trading the new one.
    - **Claiming:** Background task that checks for resolved markets and claims winnings via the gasless relayer. Enforce a 15-second delay between claims (API rate limit).
    - **Market expiration:** Stop placing new orders when less than 60 seconds remain in a market. The `market_expiring` flag prevents the bot from getting stuck with orders on an expired market.
@@ -255,7 +259,7 @@ client.get_user_positions(address)       # Current positions
 client.get_orders(trader)                # Open orders
 
 # Gasless relayer operations
-client.approve_usdc_for_settlement(addr) # One-time max USDC permit (gasless)
+client.approve_usdc_for_settlement(addr) # One-time gasless permit via API (returns dict with tx_hash)
 client.claim_winnings(contract_addr)     # Claim from a resolved market (gasless)
 client.batch_claim_winnings(addrs)       # Claim from multiple markets at once
 ```
@@ -275,8 +279,8 @@ For a deeper explanation aimed at newcomers, see `docs/prediction-markets.md`.
 - **Strike price:** The BTC price threshold set when the market opens. If BTC ends above it, YES wins. Below, NO wins. This is the anchor that every trading decision revolves around.
 - **Settlement address:** The on-chain contract that holds USDC collateral and executes trades. There's one per chain, shared across all markets. Requires a one-time gasless approval before the bot can trade.
 - **Contract address:** A per-market contract for outcome tokens (ERC1155). Only needed when claiming winnings after a market resolves — not during trading.
-- **Gasless:** Turbine's relayer pays all gas fees. Users sign messages with their private key (free, off-chain), and the relayer handles on-chain submission. This is why users only need USDC — no ETH, MATIC, or AVAX.
-- **USDC approval:** A one-time max EIP-2612 permit per settlement contract. Once approved, all future orders on that chain reuse the allowance. No per-trade approval overhead.
+- **Gasless:** The SDK is fully API-routed — all operations (approvals, claims, balance checks) go through Turbine's API, which handles on-chain submission via a relayer. Users sign messages with their private key (free, off-chain) and never need RPC access, web3, or native gas tokens (no ETH, MATIC, or AVAX). Only USDC is needed.
+- **USDC approval:** A one-time gasless EIP-2612 permit via the API's `/relayer/usdc-permit` endpoint. Returns a dict with `tx_hash`. Once approved, all future orders on that chain reuse the allowance. No per-trade approval overhead.
 - **UMA Oracle:** The decentralized oracle that resolves markets. After a market expires, UMA checks BTC's price and declares whether YES or NO wins. This is trustless — no single party controls the outcome.
 - **Pyth Network:** Provides real-time BTC price data. This is the same feed Turbine uses for market resolution, which is why the Price Action strategy (which trades based on Pyth data) is recommended — the bot's signal aligns with how winners are determined.
 

README.md

@@ -37,6 +37,9 @@ This client provides a clean, typed interface for:
 - Submitting orders to the Turbine orderbook
 - Managing positions and tracking fills
 - Subscribing to real-time orderbook updates via WebSocket
+- Gasless USDC approvals and claiming winnings via API relayer
+
+**Fully API-routed** — no RPC URL, web3 dependency, or blockchain node access required. Everything goes through `api.turbinefi.com`.
 
 ## Table of Contents
 
@@ -80,6 +83,8 @@ To trade on Turbine, you need:
 2. **API Key ID** - Identifier for your API key
 3. **API Private Key** - Ed25519 private key for authenticating API requests
 
+No RPC URL or native gas tokens are required. The SDK routes all operations through the Turbine API.
+
 ### Self-Service Registration
 
 You can register for API credentials directly using your wallet:
@@ -385,7 +390,7 @@ print(f"Current BTC: ${price.price}")
 
 ## Claiming Winnings
 
-After a market resolves, you can claim your winnings using gasless permits (no gas required).
+After a market resolves, you can claim your winnings via the API's gasless relayer (no RPC or gas tokens required).
 
 ### Single Market
 

docs/onboarding.md

@@ -65,7 +65,7 @@ TURBINE_HOST=https://api.turbinefi.com
 - `TURBINE_PRIVATE_KEY` — Your wallet's signing key. Used locally to sign transactions.
 - `TURBINE_API_KEY_ID` / `TURBINE_API_PRIVATE_KEY` — Leave blank. The bot auto-registers API credentials on first run and fills these in.
 - `CHAIN_ID=137` — Polygon mainnet, where Turbine's active markets are.
-- `TURBINE_HOST` — Turbine's API endpoint.
+- `TURBINE_HOST` — Turbine's API endpoint. All SDK operations route through this — no RPC URL or web3 needed.
 
 ## 4. Fund Your Wallet
 
@@ -111,7 +111,7 @@ python price_action_bot.py
 ### What happens on first run
 
 1. **API credentials register** — the bot signs a message with your wallet, gets API keys, and saves them to `.env`
-2. **USDC approval** — a one-time gasless permit is signed to allow trading
+2. **USDC approval** — a one-time gasless permit is signed via the API (no RPC or gas tokens needed)
 3. **Trading starts** — the bot fetches the current BTC market, runs its strategy, and places trades
 4. **Market rotation** — every 15 minutes the market expires and a new one opens. The bot switches automatically.
 5. **Claiming** — the bot claims winnings from resolved markets in the background

pyproject.toml

@@ -30,7 +30,6 @@ dependencies = [
     "eth-account>=0.13.0",
     "eth-utils>=4.1.1",
     "httpx[http2]>=0.27.0",
-    "web3>=6.0.0",
     "websockets>=12.0",
     "pynacl>=1.5.0",
     "python-dotenv>=1.0.0",