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,34 @@
+from py_clob_client.client import ClobClient
+from py_clob_client.constants import POLYMARKET_HOST
+from py_clob_client.credentials import Credentials
+
+
+def main():
+    creds = Credentials(
+        api_key="YOUR_API_KEY",
+        api_secret="YOUR_API_SECRET",
+        api_passphrase="YOUR_API_PASSPHRASE",
+    )
+
+    client = ClobClient(
+        host=POLYMARKET_HOST,
+        key=creds.api_key,
+        creds=creds,
+    )
+
+    next_cursor = None
+
+    while True:
+        response = client.get_markets(next_cursor=next_cursor)
+
+        markets = response.get("data", [])
+        for market in markets:
+            print(market.get("question"))
+
+        next_cursor = response.get("next_cursor")
+        if not next_cursor:
+            break
+
+
+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()