Improve market & order fetching clarity and update README

README.md

@@ -266,8 +266,20 @@ See [this Python example](https://gist.github.com/poly-rodr/44313920481de58d5a3f
 
 **Pro tip**: You only need to set these once per wallet. After that, you can trade freely.
 
+## Examples
+
+The `examples/` directory contains minimal Python scripts demonstrating common
+CLOB workflows:
+
+- `fetch_markets.py` – fetch active markets
+- `get_orderbook.py` – fetch a single orderbook by token_id
+- `get_orderbooks.py` – fetch multiple orderbooks in one request
+- `get_orders.py` – fetch open orders for a market (requires API credentials)
+
+These scripts are intentionally minimal and designed for quick experimentation.
+
 ## Notes
 - To discover token IDs, use the Markets API Explorer: [Get Markets](https://docs.polymarket.com/developers/gamma-markets-api/get-markets).
 - Prices are in dollars from 0.00 to 1.00. Shares are whole or fractional units of the outcome token.
 
-See [/example](/examples) for more.
+See [/example](/examples) for more.

examples/fetch_markets.py

@@ -0,0 +1,22 @@
+"""
+Minimal example: Fetch active Polymarket markets
+"""
+
+from polymarket.client import ClobClient
+
+
+def main():
+    client = ClobClient(
+        host="https://clob.polymarket.com",
+        key_id="YOUR_KEY",
+        secret="YOUR_SECRET",
+    )
+
+    markets = client.get_markets(active=True)
+
+    for market in markets[:5]:
+        print(market["question"], market["market_id"])
+
+
+if __name__ == "__main__":
+    main()

examples/get_orderbook.py

@@ -1,3 +1,10 @@
+"""
+Example: Fetch a single orderbook by token_id
+
+Requires:
+- CLOB_API_URL (optional, defaults to Polymarket public endpoint)
+"""
+
 from py_clob_client.client import ClobClient
 import os
 from dotenv import load_dotenv
@@ -18,4 +25,5 @@ def main():
     print("orderbook hash", hash)
 
 
-main()
+if __name__ == "__main__":
+    main()

examples/get_orderbooks.py

@@ -1,3 +1,11 @@
+"""
+Example: Fetch multiple orderbooks by token_id list
+
+Requires:
+- CLOB_API_URL (optional, defaults to Polymarket public endpoint)
+"""
+
+import os
 from py_clob_client.client import ClobClient
 from py_clob_client.clob_types import BookParams
 
@@ -20,4 +28,5 @@ def main():
     print("Done!")
 
 
-main()
+if __name__ == "__main__":
+    main()

examples/get_orders.py

@@ -1,3 +1,14 @@
+"""
+Example: Fetch open orders for a given market
+
+Requires:
+- CLOB_API_URL
+- PK
+- CLOB_API_KEY
+- CLOB_SECRET
+- CLOB_PASS_PHRASE
+"""
+
 import os
 
 from py_clob_client.client import ClobClient
@@ -28,4 +39,5 @@ def main():
     print("Done!")
 
 
-main()
+if __name__ == "__main__":
+    main()