You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/ai_editor/skills/tqsdk-trading-and-data/SKILL.md
+14-6Lines changed: 14 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
---
2
2
name: tqsdk-trading-and-data
3
-
description: "Explain, implement, or debug TqSdk Python workflows for wait_update or is_changing update loops, market data retrieval, historical download, account type selection, funds or positions or orders or trades, field meanings, order placement or cancelation, target-position tools, simulation, backtest, and common TqSdk errors. Use when a request mentions TqSdk, TqApi, TqAuth, TqAccount, TqKq, TqKqStock, TqSim, TqSimStock, TqMultiAccount, TqBacktest, TargetPosTask, TargetPosScheduler, DataDownloader, market data, K-line, tick, historical data, positions, trades, orders, account data, order placement, cancelation, position adjustment, field meanings, wait_update, debugging, \u884c\u60c5, K\u7ebf, \u5386\u53f2\u6570\u636e, \u6301\u4ed3, \u6210\u4ea4, \u59d4\u6258, \u8d26\u6237, \u4e0b\u5355, \u64a4\u5355, \u8c03\u4ed3, \u5b57\u6bb5\u542b\u4e49, or \u62a5\u9519."
3
+
description: "Explain, implement, or debug TqSdk Python workflows for wait_update or is_changing update loops, market data retrieval, historical download, account type selection, funds or positions or orders or trades, field meanings, order placement or cancelation, target-position tools, TqScenario margin trials, real-account margin-rate lookup, margin or risk-ratio what-if analysis, simulation, backtest, and common TqSdk errors. Use when a request mentions TqSdk, TqApi, TqAuth, TqAccount, TqKq, TqKqStock, TqSim, TqSimStock, TqMultiAccount, TqBacktest, TqScenario, TargetPosTask, TargetPosScheduler, DataDownloader, margin rate, margin calculation, risk ratio, scenario trial, market data, K-line, tick, historical data, positions, trades, orders, account data, order placement, cancelation, position adjustment, field meanings, wait_update, debugging, \u884c\u60c5, K\u7ebf, \u5386\u53f2\u6570\u636e, \u4fdd\u8bc1\u91d1\u7387, \u4fdd\u8bc1\u91d1, \u98ce\u9669\u5ea6, \u573a\u666f\u8bd5\u7b97, \u6301\u4ed3, \u6210\u4ea4, \u59d4\u6258, \u8d26\u6237, \u4e0b\u5355, \u64a4\u5355, \u8c03\u4ed3, \u5b57\u6bb5\u542b\u4e49, or \u62a5\u9519."
4
4
---
5
5
6
6
# TqSdk Trading and Data
@@ -15,11 +15,12 @@ Read only the references needed for the user's question.
15
15
2. Read [references/market-data.md](references/market-data.md) for `get_quote`, `get_kline_serial`, `get_tick_serial`, contract discovery, symbol metadata, and `DataDownloader`.
16
16
3. Read [references/account-type-matrix.md](references/account-type-matrix.md) for `TqAccount`, `TqKq`, `TqKqStock`, `TqSim`, `TqSimStock`, OTG account classes, and `TqMultiAccount`.
17
17
4. Read [references/accounts-and-trading.md](references/accounts-and-trading.md) for account, position, order, and trade getters plus multi-account getter patterns.
18
-
5. Read [references/order-functions-and-position-tools.md](references/order-functions-and-position-tools.md) for `insert_order`, `cancel_order`, `TargetPosTask`, `TargetPosScheduler`, and advanced execution helpers.
19
-
6. Read [references/object-fields.md](references/object-fields.md) when the user asks what fields mean on `Quote`, K-line or tick rows, `Account`, `Position`, `Order`, `Trade`, or their stock variants.
20
-
7. Read [references/simulation-and-backtest.md](references/simulation-and-backtest.md) for local sim, Quick sim, stock sim, backtest, and cross-account backtest limits.
21
-
8. Read [references/error-faq.md](references/error-faq.md) when the user asks about common TqSdk failures, confusing behavior, or exception messages.
22
-
9. Read [references/example-map.md](references/example-map.md) when you want a repository-backed example or doc page to imitate.
18
+
5. Read [references/scenario-and-margin.md](references/scenario-and-margin.md) for `TqScenario`, real-account margin-rate lookup, margin occupancy calculation, risk-ratio what-if analysis, and limited built-in margin discount rules.
19
+
6. Read [references/order-functions-and-position-tools.md](references/order-functions-and-position-tools.md) for `insert_order`, `cancel_order`, `TargetPosTask`, `TargetPosScheduler`, and advanced execution helpers.
20
+
7. Read [references/object-fields.md](references/object-fields.md) when the user asks what fields mean on `Quote`, K-line or tick rows, `Account`, `Position`, `Order`, `Trade`, or their stock variants.
21
+
8. Read [references/simulation-and-backtest.md](references/simulation-and-backtest.md) for local sim, Quick sim, stock sim, backtest, and cross-account backtest limits.
22
+
9. Read [references/error-faq.md](references/error-faq.md) when the user asks about common TqSdk failures, confusing behavior, or exception messages.
23
+
10. Read [references/example-map.md](references/example-map.md) when you want a repository-backed example or doc page to imitate.
23
24
24
25
## Core Rules
25
26
@@ -38,6 +39,12 @@ Read only the references needed for the user's question.
38
39
-`TargetPosTask` for target net position.
39
40
-`TargetPosScheduler` plus `twap_table` or `vwap_table` from `tqsdk.algorithm` for scheduled execution.
40
41
- Mention `InsertOrderTask` and `InsertOrderUntilAllTradedTask` as internal or advanced helpers, not the default answer.
42
+
10. Use `TqScenario` for synchronous what-if margin and risk trials, not for live order placement. It is futures-only, single-account, and updates the trial snapshot immediately after each call.
43
+
11. Explain the margin-rate source in every `TqScenario` answer:
44
+
-`account=None` or `TqSim()` uses `Quote` margin data.
45
+
-`TqAccount(...)` or `TqKq()` queries account-specific rates synchronously and may fall back to `Quote` margin if lookup fails.
46
+
12. Treat margin discounts conservatively. Reuse one `TqScenario` object for step-by-step trial actions, and do not promise broker-specific preferential rules beyond the limited built-in rules modeled by TqSdk.
47
+
13. Preserve exchange-specific close semantics in `TqScenario`. For SHFE or INE futures, keep `CLOSE` versus `CLOSETODAY` consistent with the imported position snapshot.
41
48
42
49
## Answering Style
43
50
@@ -46,3 +53,4 @@ Read only the references needed for the user's question.
46
53
- Name the exact API the user should call next.
47
54
- If behavior differs in live trading, Quick sim, local sim, stock sim, or backtest, say so explicitly.
48
55
- If the answer depends on a common pitfall, state the pitfall directly instead of burying it in examples.
56
+
- If the answer uses `TqScenario`, say what snapshot goes into `positions`, what balance goes into `init_balance`, and whether the result comes from quote margin or account-specific margin rates.
Copy file name to clipboardExpand all lines: doc/ai_editor/skills/tqsdk-trading-and-data/references/error-faq.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -103,11 +103,13 @@ Typical cause:
103
103
104
104
- the user expects polling behavior from a blocking update loop
105
105
- the code is running in Jupyter and hangs waiting for updates
106
+
- the first real-account `TqScenario` margin-rate lookup is waiting for OTG data synchronously
106
107
107
108
Fix:
108
109
109
110
- use `deadline=...` when the user truly needs a timeout
110
111
- in Jupyter, prefer simple synchronous examples and explicitly mention the limitation
112
+
- if the code uses `TqScenario(account=TqAccount(...))` or `TqScenario(account=TqKq())`, explain that the first uncached margin-rate lookup may block while TqSdk fetches the account-specific rate
-`TqScenario` creates an internal futures trading snapshot and updates it immediately after each `scenario_*` call.
45
+
-`scenario_insert_order()` matches immediately at the passed `limit_price`.
46
+
-`scenario_insert_order()` does not model partial fills. Read `status`, `volume_left`, and `last_msg`.
47
+
-`scenario_get_account()` returns only `margin` and `risk_ratio`.
48
+
-`scenario_set_margin_rate()` updates one futures symbol inside the scenario and recalculates account margin from `pre_settlement`.
49
+
50
+
## Snapshot Inputs
51
+
52
+
- Pass `positions=api.get_position()` to start from the current futures position snapshot.
53
+
- Pass one `Position` object if the user only wants to trial one symbol.
54
+
- Omit `positions` to start from an empty futures account.
55
+
- Use `init_balance` to choose the starting equity for the scenario snapshot.
56
+
- When the user wants "current positions plus extra capital", read `balance = api.get_account().balance` first, then pass `init_balance=balance + extra`.
57
+
58
+
Keep all related trial actions inside one `TqScenario` object so the margin and risk calculations stay cumulative.
59
+
60
+
## Margin-Rate Sources
61
+
62
+
-`account=None` creates an internal `TqSim()` and uses `Quote.margin` together with `pre_settlement`.
63
+
-`account=TqAccount(...)` or `account=TqKq()` triggers account-specific margin-rate lookup through the internal pre-insert-order path.
64
+
- The first uncached real-account lookup is synchronous and may spend time inside `wait_update()` before returning.
65
+
- If account-specific lookup fails, TqSdk falls back to `Quote.margin`.
66
+
- CTP margin-rate lookup is flow-controlled at roughly one new symbol per second.
67
+
-`scenario_set_margin_rate()` is the right API when the user explicitly wants to shock one futures symbol to a hypothetical new margin rate.
68
+
69
+
## Limited Margin Discount Behavior
70
+
71
+
- Reuse one `TqScenario` object and apply actions step by step when the margin result depends on net exposure after each trade.
72
+
- The reported margin change can reflect the limited built-in margin discount rules already modeled by TqSdk's simulator, including supported futures hedge and cross-period cases.
73
+
- Do not promise exact broker settlement logic for every custom preferential rule. If the user asks about a broker-specific rule that TqSdk does not model, say the result is only the built-in approximation.
74
+
75
+
## Common Patterns
76
+
77
+
### "How many lots can I still open under a 200000 margin budget?"
78
+
79
+
```python
80
+
from tqsdk import TqApi, TqAuth, TqAccount, TqScenario
81
+
82
+
account = TqAccount("broker", "acct", "pwd")
83
+
api = TqApi(account=account, auth=TqAuth("quick_user", "quick_pass"))
84
+
symbol ="SHFE.rb2611"
85
+
quote = api.get_quote(symbol)
86
+
positions = api.get_position()
87
+
88
+
with TqScenario(api, account=account, positions=positions) as s:
89
+
base_margin = s.scenario_get_account().margin
90
+
lots =0
91
+
whileTrue:
92
+
order = s.scenario_insert_order(symbol, "BUY", "OPEN", 1, quote.last_price)
93
+
if order.status =="FINISHED"and order.volume_left >0:
94
+
break
95
+
lots +=1
96
+
if s.scenario_get_account().margin - base_margin >200000:
### "What happens if the futures margin rate becomes 15%?"
103
+
104
+
```python
105
+
account = TqAccount("broker", "acct", "pwd")
106
+
api = TqApi(account=account, auth=TqAuth("quick_user", "quick_pass"))
107
+
positions = api.get_position()
108
+
109
+
with TqScenario(api, account=account, positions=positions) as s:
110
+
before = s.scenario_get_account()
111
+
s.scenario_set_margin_rate("SHFE.rb2611", 0.15)
112
+
after = s.scenario_get_account()
113
+
```
114
+
115
+
### "What happens if I add 100000 equity and keep positions unchanged?"
116
+
117
+
```python
118
+
account = TqAccount("broker", "acct", "pwd")
119
+
api = TqApi(account=account, auth=TqAuth("quick_user", "quick_pass"))
120
+
positions = api.get_position()
121
+
balance = api.get_account().balance
122
+
123
+
with TqScenario(api, account=account, positions=positions, init_balance=balance +100000) as s:
124
+
after = s.scenario_get_account()
125
+
```
126
+
127
+
## Boundaries
128
+
129
+
-`TqScenario` currently supports futures only.
130
+
-`TqScenario` currently supports one account snapshot at a time.
131
+
-`TqScenario` is synchronous. Run it outside the hot `wait_update()` loop when possible.
132
+
-`scenario_insert_order()` always fills immediately at the passed price inside the trial snapshot.
133
+
-`scenario_insert_order()` and `scenario_get_account()` return reduced objects, not the full live `Order` or `Account`.
134
+
- Preserve `CLOSE` versus `CLOSETODAY` when closing SHFE or INE positions imported from a live snapshot.
135
+
- Do not recommend `TqScenario` for stock trading, option pricing shocks, or arbitrary custom broker discount tables that the simulator does not model.
0 commit comments