PerpOB

.env.example

@@ -1,32 +1,48 @@
-### Cronos (testnet)
+### Devnet1 (perpOB testnet)
 CHAIN_ID=89346162
-REYA_WS_URL="wss://websocket-testnet.reya.xyz/"
-REYA_WS_EXEC_URL="wss://ws-exec-testnet.reya.xyz"
-REYA_API_URL="https://api-cronos.reya.xyz/v2"
+REYA_WS_URL="wss://websocket-devnet.reya-cronos.network/"
+REYA_WS_EXEC_URL="wss://ws-exec-devnet.reya-cronos.network"
+REYA_API_URL="https://api-devnet.reya-cronos.network/v2"
+# OrdersGateway proxy = the EIP-712 verifyingContract.
+REYA_ORDERS_GATEWAY="0x7Ec89E555c771D2B5939aBE5C4E4291852633D4D"
+
+### Cronos testnet (same chain id as devnet1, different deployment)
+#CHAIN_ID=89346162
+#REYA_WS_URL="wss://websocket-testnet.reya.xyz/"
+#REYA_WS_EXEC_URL="wss://ws-exec-testnet.reya.xyz"
+#REYA_API_URL="https://api-cronos.reya.xyz/v2"
+# Cronos shares devnet1's chain id, so set the gateway explicitly to target it:
+#REYA_ORDERS_GATEWAY="0x5a0ac2f89e0bdeafc5c549e354842210a3e87ca5"
 
 ### Reya Network (mainnet)
 #CHAIN_ID=1729
 #REYA_WS_URL="wss://ws.reya.xyz/"
 #REYA_WS_EXEC_URL="wss://ws-exec.reya.xyz"
 #REYA_API_URL="https://api.reya.xyz/v2"
+#REYA_ORDERS_GATEWAY="0xfc8c96be87da63cecddbf54abfa7b13ee8044739"
 
 ### Staging (uses mainnet chain ID 1729)
 #CHAIN_ID=1729
 #REYA_WS_URL="wss://websocket-staging.reya.xyz"
 #REYA_WS_EXEC_URL="wss://ws-exec-staging.reya.xyz"
 #REYA_API_URL="https://api-staging.reya.xyz/v2"
 
-# PERP_ACCOUNT_ID_1
+# PERP_ACCOUNT_ID_1 (default single-account perp tester)
 PERP_ACCOUNT_ID_1=
 PERP_PRIVATE_KEY_1=
 PERP_WALLET_ADDRESS_1=
 
-# SPOT_ACCOUNT_ID_1
+# PERP_ACCOUNT_ID_2 (used as the perp taker in maker/taker tests; perp orderbook needs both sides)
+PERP_ACCOUNT_ID_2=
+PERP_PRIVATE_KEY_2=
+PERP_WALLET_ADDRESS_2=
+
+# SPOT_ACCOUNT_ID_1 (spot maker)
 SPOT_ACCOUNT_ID_1=
 SPOT_PRIVATE_KEY_1=
 SPOT_WALLET_ADDRESS_1=
 
-# SPOT_ACCOUNT_ID_2
+# SPOT_ACCOUNT_ID_2 (spot taker)
 SPOT_ACCOUNT_ID_2=
 SPOT_PRIVATE_KEY_2=
 SPOT_WALLET_ADDRESS_2=

.gitignore

@@ -627,3 +627,5 @@ testing.py
 
 # End of https://www.gitignore.io/api/osx,python,pycharm,windows,visualstudio,visualstudiocode
 examples/config.json
+
+.claude/

.openapi-generator/FILES

@@ -22,6 +22,8 @@ sdk/open_api/models/create_order_request.py
 sdk/open_api/models/create_order_response.py
 sdk/open_api/models/depth.py
 sdk/open_api/models/depth_type.py
+sdk/open_api/models/execution_bust.py
+sdk/open_api/models/execution_bust_list.py
 sdk/open_api/models/execution_type.py
 sdk/open_api/models/fee_tier_parameters.py
 sdk/open_api/models/global_fee_parameters.py
@@ -45,8 +47,6 @@ sdk/open_api/models/server_error.py
 sdk/open_api/models/server_error_code.py
 sdk/open_api/models/side.py
 sdk/open_api/models/spot_execution.py
-sdk/open_api/models/spot_execution_bust.py
-sdk/open_api/models/spot_execution_bust_list.py
 sdk/open_api/models/spot_execution_list.py
 sdk/open_api/models/spot_market_definition.py
 sdk/open_api/models/spot_market_summary.py

AGENTS.md

@@ -0,0 +1,152 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## Important Notes
+* Always read entire files. Otherwise, you don’t know what you don’t know, and will end up making mistakes, duplicating code that already exists, or misunderstanding the architecture.
+* Commit early and often. When working on large tasks, your task could be broken down into multiple logical milestones. After a certain milestone is completed and confirmed to be ok by the user, you should commit it. If you do not, if something goes wrong in further steps, we would need to end up throwing away all the code, which is expensive and time consuming.
+* Your internal knowledgebase of libraries might not be up to date. When working with any external library, unless you are 100% sure that the library has a super stable interface, you will look up the latest syntax and usage via either Perplexity (first preference) or web search (less preferred, only use if Perplexity is not available)
+* Do not say things like: “x library isn’t working so I will skip it”. Generally, it isn’t working because you are using the incorrect syntax or patterns. This applies doubly when the user has explicitly asked you to use a specific library, if the user wanted to use another library they wouldn’t have asked you to use a specific one in the first place.
+* Always run linting after making major changes. Otherwise, you won’t know if you’ve corrupted a file or made syntax errors, or are using the wrong methods, or using methods in the wrong way.
+* Please organise code into separate files wherever appropriate, and follow general coding best practices about variable naming, modularity, function complexity, file sizes, commenting, etc.
+* Code is read more often than it is written, make sure your code is always optimised for readability
+* Unless explicitly asked otherwise, the user never wants you to do a “dummy” implementation of any given task. Never do an implementation where you tell the user: “This is how it *would* look like”. Just implement the thing.
+* Whenever you are starting a new task, it is of utmost importance that you have clarity about the task. You should ask the user follow up questions if you do not, rather than making incorrect assumptions.
+* Do not carry out large refactors unless explicitly instructed to do so.
+* When starting on a new task, you should first understand the current architecture, identify the files you will need to modify, and come up with a Plan. In the Plan, you will think through architectural aspects related to the changes you will be making, consider edge cases, and identify the best approach for the given task. Get your Plan approved by the user before writing a single line of code.
+* If you are running into repeated issues with a given task, figure out the root cause instead of throwing random things at the wall and seeing what sticks, or throwing in the towel by saying “I’ll just use another library / do a dummy implementation”.
+* You are an incredibly talented and experienced polyglot with decades of experience in diverse areas such as software architecture, system design, development, UI & UX, copywriting, and more.
+* When doing UI & UX work, make sure your designs are both aesthetically pleasing, easy to use, and follow UI / UX best practices. You pay attention to interaction patterns, micro-interactions, and are proactive about creating smooth, engaging user interfaces that delight users.
+* When you receive a task that is very large in scope or too vague, you will first try to break it down into smaller subtasks. If that feels difficult or still leaves you with too many open questions, push back to the user and ask them to consider breaking down the task for you, or guide them through that process. This is important because the larger the task, the more likely it is that things go wrong, wasting time and energy for everyone involved.
+
+
+## Project Overview
+
+This is the Reya Python SDK, providing Python interfaces for interacting with the Reya ecosystem. The SDK consists of three main components:
+
+- **REST API Client** (`sdk/reya_rest_api/`) - HTTP client for Reya's Trading API
+- **RPC Client** (`sdk/reya_rpc/`) - Web3-based client for on-chain actions
+- **WebSocket Client** (`sdk/reya_websocket/`) - Real-time data streaming client
+
+## Development Commands
+
+### Setup and Installation
+```bash
+# Install dependencies
+poetry install
+
+# Activate virtual environment
+poetry shell
+# Or use: source $(poetry env info --path)/bin/activate
+```
+
+### Code Quality and Testing
+```bash
+# Run all linting and formatting (via pre-commit)
+make lint
+# Or: make pre-commit
+
+# Run specific linter only
+make pre-commit hook=black
+make pre-commit hook=isort
+make pre-commit hook=flake8
+make pre-commit hook=mypy
+
+# Install additional type stubs for mypy
+make install-types
+
+# Run security checks
+make check-safety
+
+# Clean build artifacts
+make cleanup
+```
+
+### Dependency Management
+```bash
+# Update poetry.lock
+make lockfile-update
+
+# Fully regenerate poetry.lock
+make lockfile-update-full
+
+# Update dev dependencies to latest
+make update-dev-deps
+```
+
+### Running Examples
+```bash
+# Activate environment first
+poetry shell
+
+# Run examples using module notation
+python -m examples.rest_api.wallet_example
+python -m examples.websocket.market_monitoring
+python -m examples.rpc.trade_execution
+```
+
+## Architecture Overview
+
+### REST API Client Architecture
+The REST API client (`sdk/reya_rest_api/`) follows a resource-based pattern:
+
+- **Client** (`client.py`) - Main entry point with signature authentication
+- **Resources** (`resources/`) - Organized by API endpoints (wallet, markets, orders, assets, prices)
+- **Auth** (`auth/signatures.py`) - EIP-712 signature generation for authenticated requests
+- **Models** (`models/`) - Pydantic models for request/response data
+- **Config** (`config.py`) - Configuration management with environment variable support
+
+### RPC Client Architecture  
+The RPC client (`sdk/reya_rpc/`) provides Web3-based blockchain interactions:
+
+- **Actions** (`actions/`) - High-level transaction builders for common operations
+- **ABIs** (`abis/`) - Smart contract ABIs for all supported contracts
+- **Config** (`config.py`) - Network-specific contract addresses and configuration
+- **Utils** (`utils/`) - Core transaction execution utilities
+
+### WebSocket Client Architecture
+The WebSocket client (`sdk/reya_websocket/`) offers resource-oriented real-time data access:
+
+- **Socket** (`socket.py`) - Main WebSocket connection manager with auto-reconnection
+- **Resources** (`resources/`) - Market, wallet, and price subscription managers
+- **Config** (`config.py`) - WebSocket connection configuration
+
+### Key Configuration Patterns
+
+The codebase uses environment variables extensively for configuration:
+
+- **Trading API**: Uses `TradingConfig.from_env()` to load API URLs, authentication, etc.
+- **RPC**: Uses `get_config()` to load chain IDs, contract addresses, private keys
+- **WebSocket**: Uses `WebSocketConfig.from_env()` for connection parameters
+
+### Smart Contract Integration
+
+The RPC client supports two main networks:
+- **Mainnet** (chain_id=1729): Production Reya network
+- **Testnet** (chain_id=89346162): Testing environment
+
+Contract addresses are network-specific and configured in `sdk/reya_rpc/config.py`.
+
+### Code Quality Configuration
+
+- **Line length**: 120 characters (Black, isort, Pylint)
+- **Python version**: 3.12+ required, 3.10 for type checking
+- **Type checking**: Strict mypy configuration with comprehensive checks
+- **Pre-commit hooks**: Automated formatting and linting on commit
+
+## Environment Setup Requirements
+
+Create `.env` file with:
+```
+ACCOUNT_ID=your_account_id
+PRIVATE_KEY=your_private_key  
+CHAIN_ID=1729  # or 89346162 for testnet
+REYA_WS_URL=wss://ws.reya.xyz/
+```
+
+## Testing Approach
+
+The project uses pytest with additional packages:
+- `pytest-recording` and `vcrpy` for HTTP request/response recording
+- `pytest-cov` for coverage reporting
+- Test files should be placed alongside source code or in dedicated test directories

CLAUDE.md

@@ -39,6 +39,11 @@ python -m examples.websocket.market_monitoring
 python -m examples.rpc.trade_execution
 ```
 
+## Testing against devnet
+* The integration suites (`tests/test_orderbook`, `test_perps`, `test_spot`, `ws_exec`) run **live against devnet** — they place real orders, fill, settle on-chain, and assert on executions/balances.
+* **Before running the suite, kill any long-running example scripts** (e.g. `examples.websocket.perps.depth_market_maker`, any `python -m examples.*`). They maintain resting orders / open positions on the shared devnet test accounts and **pollute test state** — symptoms include `cancelledCount` mismatches, "reduce-only not rejected" (a leftover position exists), and matching against the wrong counterparty. Check with `ps -Ao pid,etime,command | grep -iE "examples\.|market_maker"` and kill stragglers before a run.
+* Tests share a small pool of devnet accounts; leftover orders from a crashed/aborted run can also pollute — a clean run starts from no resting orders / no open positions on the test accounts.
+
 ## Key Architecture
 - REST: client.py (main entry) -> resources/ (endpoints) -> auth/signatures.py (EIP-712) -> models/ (Pydantic)
 - RPC: actions/ (tx builders) -> abis/ (contract ABIs) -> config.py (network addresses)

README.md

@@ -165,8 +165,8 @@ Create a `.env` file in the project root with the following variables:
 ACCOUNT_ID=your_account_id
 PRIVATE_KEY=your_private_key
 CHAIN_ID=1729                   # Use 89346162 for testnet
-REYA_WS_URL=wss://ws.reya.xyz/  # Use wss://websocket-testnet.reya.xyz/ for testnet
-REYA_API_BASE_URL=https://api.reya.xyz/v2  # Use https://api-cronos.reya.xyz/v2 for testnet
+REYA_WS_URL=wss://ws.reya.xyz/  # Use wss://websocket-devnet.reya-cronos.network/ for devnet1 (perpOB testnet)
+REYA_API_BASE_URL=https://api.reya.xyz/v2  # Use https://api-devnet.reya-cronos.network/v2 for devnet1
 OWNER_WALLET_ADDRESS=your_wallet_address    # Required: wallet address for data queries
 ```
 

examples/rest_api/perps/order_entry.py

@@ -143,8 +143,9 @@ async def run_stop_loss_orders_test(client: ReyaTradingClient):
         TriggerOrderParameters(
             symbol="ETHRUSDPERP",
             is_buy=False,
+            qty="0.01",
             trigger_px="1000",
-            trigger_type=OrderType.SL,
+            trigger_type=OrderType.STOP_LOSS,
         )
     )
     long_sl_response = handle_order_response("Stop Loss (Long Position)", response)
@@ -155,8 +156,9 @@ async def run_stop_loss_orders_test(client: ReyaTradingClient):
         TriggerOrderParameters(
             symbol="ETHRUSDPERP",
             is_buy=True,
+            qty="0.01",
             trigger_px="9000",
-            trigger_type=OrderType.SL,
+            trigger_type=OrderType.STOP_LOSS,
         )
     )
     short_sl_response = handle_order_response("Stop Loss (Short Position)", response)
@@ -174,8 +176,9 @@ async def run_take_profit_orders_test(client: ReyaTradingClient):
         TriggerOrderParameters(
             symbol="ETHRUSDPERP",
             is_buy=False,
+            qty="0.01",
             trigger_px="10000",
-            trigger_type=OrderType.TP,
+            trigger_type=OrderType.TAKE_PROFIT,
         )
     )
     long_tp_response = handle_order_response("Take Profit (Long Position)", response)
@@ -186,8 +189,9 @@ async def run_take_profit_orders_test(client: ReyaTradingClient):
         TriggerOrderParameters(
             symbol="ETHRUSDPERP",
             is_buy=True,
+            qty="0.01",
             trigger_px="1500",
-            trigger_type=OrderType.TP,
+            trigger_type=OrderType.TAKE_PROFIT,
         )
     )
     short_tp_response = handle_order_response("Take Profit (Short Position)", response)
@@ -209,7 +213,11 @@ async def run_order_cancellation_test(client: ReyaTradingClient, order_ids: list
     order_id = valid_order_ids[0]
     logger.info(f"Attempting to cancel order: {order_id}")
 
-    response = await client.cancel_order(order_id=order_id)
+    response = await client.cancel_order(
+        symbol="ETHRUSDPERP",
+        account_id=client.config.account_id,
+        order_id=order_id,
+    )
     handle_order_response("Order Cancellation", response)
 
 

examples/rest_api/spot/cancel_order_by_id.py

@@ -49,7 +49,7 @@ async def main() -> None:
     wallet_address = wallet.address
 
     # Determine API URL based on chain
-    api_url = "https://api.reya.xyz/v2" if chain_id == MAINNET_CHAIN_ID else "https://api-cronos.reya.xyz/v2"
+    api_url = "https://api.reya.xyz/v2" if chain_id == MAINNET_CHAIN_ID else "https://api-devnet.reya-cronos.network/v2"
 
     print("=" * 60)
     print("CANCEL ORDER BY ID")

examples/rest_api/spot/spot_trade.py

@@ -18,6 +18,8 @@
     python -m examples.rest_api.spot.spot_trade
 """
 
+from __future__ import annotations
+
 import asyncio
 import logging
 import sys

examples/rest_api/spot/spot_transfer.py

@@ -23,6 +23,8 @@
         --qty 5
 """
 
+from __future__ import annotations
+
 import argparse
 import asyncio
 import logging