Skip to content

Commit 21fca30

Browse files
pcriadoperezpcriadoperez
committed
feat: add LLM-friendly documentation and agent skill
Add llms.txt (concise overview) and llms-full.txt (full method reference) following the llmstxt.org standard, plus a cross-client Agent Skill (.agents/skills/) compatible with 30+ coding agents and a Claude Code plugin for marketplace distribution. - generate_llms_txt.py: auto-generates both files by introspecting Client - .agents/skills/python-binance/: agentskills.io-compatible skill - python-binance-plugin/: Claude Code plugin wrapping the same skill - README.rst: add LLM & AI Agent Support section with npx install command
1 parent 6dd5d72 commit 21fca30

8 files changed

Lines changed: 15103 additions & 0 deletions

File tree

‎.agents/skills/python-binance/SKILL.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
---
2+
name: python-binance
3+
description: >
4+
Help developers use the python-binance library for trading on Binance.
5+
Use when code imports binance, references Client/AsyncClient, or asks
6+
about Binance API trading, market data, websockets, or account management.
7+
---
8+
9+
# python-binance SDK
10+
11+
Unofficial Python SDK for the Binance cryptocurrency exchange. 798+ methods covering Spot, Margin, Futures, Options, Portfolio Margin, and WebSocket APIs.
12+
13+
## Setup
14+
15+
```python
16+
from binance import Client, AsyncClient
17+
18+
# Sync client
19+
client = Client(api_key, api_secret)
20+
21+
# Async client
22+
client = await AsyncClient.create(api_key, api_secret)
23+
24+
# Testnet
25+
client = Client(api_key, api_secret, testnet=True)
26+
27+
# Demo/paper trading
28+
client = Client(api_key, api_secret, demo=True)
29+
30+
# RSA key auth
31+
client = Client(api_key, private_key=open("key.pem").read())
32+
33+
# Other TLD (Binance US, Japan, etc.)
34+
client = Client(api_key, api_secret, tld="us")
35+
```
36+
37+
## Critical Patterns
38+
39+
1. **All methods return plain Python dicts** — not custom objects. Access fields with `response["key"]`.
40+
2. **`**params` kwargs** — most methods accept extra Binance API parameters as keyword arguments.
41+
3. **Sync/async parity** — `Client` and `AsyncClient` have identical method names. Use `await` for async.
42+
4. **Enums** — import from `binance.enums` or use string values directly (`"BUY"`, `"LIMIT"`, etc.).
43+
44+
## Method Naming Convention
45+
46+
This is the most important pattern — it lets you infer method names:
47+
48+
| Prefix | Domain | Example |
49+
|--------|--------|---------|
50+
| `get_*` / `create_*` / `cancel_*` | Spot | `get_order_book()`, `create_order()` |
51+
| `futures_*` | USD-M Futures | `futures_create_order()` |
52+
| `futures_coin_*` | Coin-M Futures | `futures_coin_create_order()` |
53+
| `margin_*` | Margin | `margin_borrow_repay()` |
54+
| `options_*` | Vanilla Options | `options_place_order()` |
55+
| `papi_*` | Portfolio Margin | `papi_create_um_order()` |
56+
| `ws_*` | WebSocket CRUD | `ws_create_order()` |
57+
| `order_*` | Order helpers | `order_limit_buy()` |
58+
| `stream_*` | User data stream | `stream_get_listen_key()` |
59+
60+
## Key Enums
61+
62+
```python
63+
from binance.enums import *
64+
65+
SIDE_BUY, SIDE_SELL = "BUY", "SELL"
66+
ORDER_TYPE_LIMIT, ORDER_TYPE_MARKET = "LIMIT", "MARKET"
67+
ORDER_TYPE_STOP_LOSS_LIMIT = "STOP_LOSS_LIMIT"
68+
TIME_IN_FORCE_GTC = "GTC" # Good till cancelled
69+
TIME_IN_FORCE_IOC = "IOC" # Immediate or cancel
70+
KLINE_INTERVAL_1MINUTE = "1m"
71+
KLINE_INTERVAL_1HOUR = "1h"
72+
KLINE_INTERVAL_1DAY = "1d"
73+
FUTURE_ORDER_TYPE_MARKET = "MARKET"
74+
FUTURE_ORDER_TYPE_LIMIT = "LIMIT"
75+
```
76+
77+
## Common Tasks
78+
79+
### Get current price
80+
```python
81+
ticker = client.get_symbol_ticker(symbol="BTCUSDT")
82+
print(ticker["price"]) # "50000.00000000"
83+
```
84+
85+
### Get account balances
86+
```python
87+
account = client.get_account()
88+
balances = [b for b in account["balances"] if float(b["free"]) > 0]
89+
```
90+
91+
### Place a market buy order
92+
```python
93+
from binance.enums import *
94+
order = client.create_order(
95+
symbol="BTCUSDT",
96+
side=SIDE_BUY,
97+
type=ORDER_TYPE_MARKET,
98+
quoteOrderQty=100 # spend 100 USDT
99+
)
100+
```
101+
102+
### Place a limit sell order
103+
```python
104+
order = client.create_order(
105+
symbol="BTCUSDT",
106+
side=SIDE_SELL,
107+
type=ORDER_TYPE_LIMIT,
108+
timeInForce=TIME_IN_FORCE_GTC,
109+
quantity=0.001,
110+
price="60000"
111+
)
112+
```
113+
114+
### Get order status
115+
```python
116+
order = client.get_order(symbol="BTCUSDT", orderId=12345)
117+
print(order["status"]) # "FILLED", "NEW", "CANCELED"
118+
```
119+
120+
### Cancel an order
121+
```python
122+
result = client.cancel_order(symbol="BTCUSDT", orderId=12345)
123+
```
124+
125+
### Get historical klines (candlesticks)
126+
```python
127+
klines = client.get_historical_klines("BTCUSDT", Client.KLINE_INTERVAL_1HOUR, "1 day ago UTC")
128+
# Each kline: [open_time, open, high, low, close, volume, close_time, ...]
129+
```
130+
131+
### Get order book depth
132+
```python
133+
depth = client.get_order_book(symbol="BTCUSDT")
134+
print(depth["bids"][:5]) # [[price, qty], ...]
135+
```
136+
137+
### Futures: place an order
138+
```python
139+
order = client.futures_create_order(
140+
symbol="BTCUSDT", side="BUY", type="MARKET", quantity=0.001
141+
)
142+
```
143+
144+
### Futures: get position info
145+
```python
146+
positions = client.futures_position_information(symbol="BTCUSDT")
147+
```
148+
149+
## WebSocket Streaming
150+
151+
```python
152+
from binance import ThreadedWebsocketManager
153+
154+
twm = ThreadedWebsocketManager(api_key=api_key, api_secret=api_secret)
155+
twm.start()
156+
157+
def handle_message(msg):
158+
print(msg)
159+
160+
twm.start_kline_socket(callback=handle_message, symbol="BTCUSDT")
161+
twm.join()
162+
```
163+
164+
### Async WebSocket
165+
```python
166+
from binance import AsyncClient, BinanceSocketManager
167+
168+
async def main():
169+
client = await AsyncClient.create()
170+
bsm = BinanceSocketManager(client)
171+
async with bsm.trade_socket("BTCUSDT") as ts:
172+
for _ in range(10):
173+
msg = await ts.recv()
174+
print(msg)
175+
await client.close_connection()
176+
```
177+
178+
## Error Handling
179+
180+
```python
181+
from binance.exceptions import BinanceAPIException
182+
183+
try:
184+
order = client.create_order(...)
185+
except BinanceAPIException as e:
186+
print(e.code) # e.g., -1013
187+
print(e.message) # e.g., "Filter failure: LOT_SIZE"
188+
print(e.status_code)
189+
```
190+
191+
## Full Reference
192+
193+
For the complete method reference with all 798+ methods, signatures, and parameters, see:
194+
- `llms-full.txt` in the repository root
195+
- `Endpoints.md` for endpoint-to-method mapping

‎.agents/skills/python-binance/references/REFERENCE.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# python-binance Full Method Reference
2+
3+
This reference points to the comprehensive auto-generated method documentation.
4+
5+
## Primary Reference
6+
7+
The full method reference with all 798+ methods, their signatures, parameters, and response examples is available at:
8+
9+
**[llms-full.txt](../../../../llms-full.txt)**
10+
11+
This file is auto-generated by `generate_llms_txt.py` and contains every public method in the `Client` class, organized by category:
12+
13+
- **Spot / General** — Market data, trading, account management, wallet operations
14+
- **Futures USD-M** — USD-margined futures trading
15+
- **Futures Coin-M** — Coin-margined futures trading
16+
- **Margin** — Cross and isolated margin trading
17+
- **Options** — Vanilla options trading
18+
- **Portfolio Margin** — Portfolio margin (unified account) operations
19+
- **WebSocket API** — Order management over WebSocket for low latency
20+
- **WebSocket Futures** — Futures operations over WebSocket
21+
- **Gift Card** — Binance gift card operations
22+
- **Convert** — Crypto conversion operations
23+
24+
## Other References
25+
26+
- **[Endpoints.md](../../../../Endpoints.md)** — Maps every Binance API endpoint to its python-binance method
27+
- **[Binance API Docs](https://developers.binance.com/docs/)** — Official Binance API documentation
28+
- **[python-binance ReadTheDocs](https://python-binance.readthedocs.io/en/latest/)** — Official library documentation
29+
30+
## Regenerating
31+
32+
To regenerate the full reference after library updates:
33+
34+
```bash
35+
python generate_llms_txt.py
36+
```

‎README.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -310,6 +310,27 @@ Python-binance also supports `orjson` for parsing JSON since it is much faster t
310310

311311
However, `orjson` is not enabled by default because it is not supported by every python interpreter. If you want to opt-in, you just need to install it (`pip install orjson`) on your local environment. Python-binance will detect the installion and pick it up automatically.
312312

313+
LLM & AI Agent Support
314+
----------------------
315+
316+
This library includes resources to help AI coding assistants (Claude Code, Cursor, Copilot, etc.):
317+
318+
- ``llms.txt`` — Concise library overview for LLMs (`llmstxt.org <https://llmstxt.org>`_ standard)
319+
- ``llms-full.txt`` — Complete API reference for LLMs (all 798+ methods with signatures and parameters)
320+
- ``.agents/skills/python-binance/`` — Agent Skill (works with any `Agent Skills <https://agentskills.io>`_ compatible tool)
321+
- ``generate_llms_txt.py`` — Script to regenerate the LLM files after library updates
322+
323+
**Install the agent skill** into any project or globally with `npx skills <https://www.npmjs.com/package/skills>`_
324+
(works with Claude Code, Cursor, Copilot, Gemini CLI, Goose, Roo Code, and 30+ other agents):
325+
326+
.. code:: bash
327+
328+
# Install into the current project
329+
npx -y skills add sammchardy/python-binance
330+
331+
# Install globally (available in all projects)
332+
npx -y skills add sammchardy/python-binance --global
333+
313334
Star history
314335
------------
315336

0 commit comments

Comments
 (0)