Add Nado documentation and examples, including new API endpoints, FAQs, and guides for using the TypeScript SDK. Update .env.example with additional configuration options.

This commit is contained in:
discountry
2025-12-19 01:38:09 +08:00
parent 624fecfa70
commit c69ea72860
148 changed files with 17031 additions and 27 deletions
@@ -0,0 +1,54 @@
# Cancel Orders
## Request
{% tabs %}
{% tab title="REST" %} <mark style="color:orange;">`POST [TRIGGER_ENDPOINT]/execute`</mark>
**Body**
```json
{
"cancel_orders": {
"tx": {
"sender": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
"productIds": [0],
"digests": ["0x"],
"nonce": "1"
},
"signature": "0x"
}
}
```
{% endtab %}
{% endtabs %}
## Request Parameters
See [Core > Executes > Cancel Orders](https://docs.nado.xyz/developer-resources/gateway/executes/cancel-orders#request-parameters)
## Response
#### Success
```json
{
"status": "success",
"signature": {signature},
"request_type": "execute_cancel_orders"
}
```
#### Failure
```json
{
"status": "failure",
"signature": {signature},
"error": "{error_msg}",
"error_code": {error_code},
"request_type": "execute_cancel_orders"
}
```
@@ -0,0 +1,53 @@
# Cancel Product Orders
## Request
{% tabs %}
{% tab title="REST" %} <mark style="color:orange;">`POST [TRIGGER_ENDPOINT]/execute`</mark>
**Body**
```json
{
"cancel_product_orders": {
"tx": {
"sender": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
"productIds": [0],
"nonce": "1"
},
"signature": "0x",
"digest": "0x"
}
}
```
{% endtab %}
{% endtabs %}
## Request Parameters
See [Core > Executes > Cancel Product Orders](https://docs.nado.xyz/developer-resources/gateway/executes/cancel-product-orders#request-parameters)
## Response
#### Success
```json
{
"status": "success",
"signature": {signature},
"request_type": "execute_cancel_product_orders"
}
```
#### Failure
```json
{
"status": "failure",
"signature": {signature},
"error": "{error_msg}",
"error_code": {error_code},
"request_type": "execute_cancel_product_orders"
}
```
@@ -0,0 +1,240 @@
# Place Order
## Rate limits
* A max of 25 pending trigger orders per product per subaccount
{% hint style="info" %}
See more details in [Trigger Service Limits](https://docs.nado.xyz/developer-resources/rate-limits#trigger-service-limits).
{% endhint %}
## Request
{% tabs %}
{% tab title="Price Trigger" %} <mark style="color:orange;">`POST [TRIGGER_ENDPOINT]/execute`</mark>
**Body**
```json
{
"place_order": {
"product_id": 1,
"order": {
"sender": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
"priceX18": "9900000000000000000000",
"amount": "1000000000000000000",
"expiration": "4294967295",
"nonce": "1757062078359666688"
},
"trigger": {
"price_trigger": {
"price_requirement": {
"oracle_price_below": "9900000000000000000000"
}
}
},
"signature": "0x",
"id": 100
}
}
```
{% endtab %}
{% tab title="TWAP Trigger" %} <mark style="color:orange;">`POST [TRIGGER_ENDPOINT]/execute`</mark>
**Body**
```json
{
"place_order": {
"product_id": 1,
"order": {
"sender": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
"priceX18": "9900000000000000000000",
"amount": "5000000000000000000",
"expiration": "4294967295",
"nonce": "1757062078359666688",
"appendix": "21474836490"
},
"trigger": {
"time_trigger": {
"interval": 30,
"amounts": ["1000000000000000000", "1000000000000000000", "1000000000000000000", "1000000000000000000", "1000000000000000000"]
}
},
"signature": "0x",
"id": 100
}
}
```
{% endtab %}
{% endtabs %}
## Request Parameters
<table><thead><tr><th width="180" align="center">Parameter</th><th width="94" align="center">Type</th><th width="112" align="center">Required</th><th>Description</th></tr></thead><tbody><tr><td align="center">product_id</td><td align="center">number</td><td align="center">Yes</td><td>Id of spot / perp product for which to place order. Use <a href="../../gateway/queries/all-products">All products</a> query to retrieve all valid product ids.</td></tr><tr><td align="center">order</td><td align="center">object</td><td align="center">Yes</td><td>Order object, see <a href="../../../gateway/executes/place-order#signing">Signing</a> section for details on each order field.</td></tr><tr><td align="center">signature</td><td align="center">string</td><td align="center">Yes</td><td>Hex string representing hash of the <strong>signed</strong> order. See <a href="../../../gateway/executes/place-order#signing">Signing</a> section for more details.</td></tr><tr><td align="center">trigger</td><td align="center">object</td><td align="center">Yes</td><td>Trigger criteria can be either:<br><strong>Price-based:</strong> <mark style="color:red;"><code>{"price_trigger": {"price_requirement": {"oracle_price_above": "{PRICE}"}}}</code></mark><br><strong>Time-based (TWAP):</strong> <mark style="color:red;"><code>{"time_trigger": {"interval": {SECONDS}, "amounts": ["{AMOUNT1}", "{AMOUNT2}", ...]}}</code></mark></td></tr><tr><td align="center">digest</td><td align="center">string</td><td align="center">No</td><td>Hex string representing a hash of the order.</td></tr><tr><td align="center">spot_leverage</td><td align="center">boolean</td><td align="center">No</td><td>Indicates whether leverage should be used; when set to <mark style="color:red;"><code>false</code></mark> , placing the order fails if the transaction causes a borrow on the subaccount. Defaults to <mark style="color:red;"><code>true</code></mark>.</td></tr><tr><td align="center">id</td><td align="center">number</td><td align="center">No</td><td>An optional id that when provided is returned as part of <mark style="color:red;"><code>Fill</code></mark> and <mark style="color:red;"><code>OrderUpdate</code></mark> stream events when the order is triggered / executed. See <a href="../../gateway/executes/place-order">gateway > place order</a> and <a href="../../subscriptions">subscriptions</a> for more details.</td></tr></tbody></table>
{% hint style="info" %}
**Price Trigger Options:**
* <mark style="color:red;">`oracle_price_above`</mark>: Order is triggered if the oracle price is above or at the indicated price.
* <mark style="color:red;">`oracle_price_below`</mark>: Order is triggered if the oracle price is below or at the indicated price.
* <mark style="color:red;">`last_price_above`</mark>: Order is triggered if the last trade price is above or at the indicated price.
* <mark style="color:red;">`last_price_below`</mark>: Order is triggered if the last trade price is below or at the indicated price.
* <mark style="color:red;">`mid_price_above`</mark>: Order is triggered if the mid book price is above or at the indicated price.
* <mark style="color:red;">`mid_price_below`</mark>: Order is triggered if the mid book price is below or at the indicated price.
**TWAP (Time-Weighted Average Price) Trigger:**
* <mark style="color:red;">`time_trigger`</mark>: Executes orders at regular intervals over time.
* <mark style="color:red;">`interval`</mark>: Time in seconds between each execution.
* <mark style="color:red;">`amounts`</mark>: Optional array specifying the exact amount for each execution. If not provided, the total order amount is split evenly across executions.
* **TWAP orders must use IOC (Immediate or Cancel) execution type only**
* **TWAP orders cannot be combined with isolated margin**
* Use the <mark style="color:red;">`list_twap_executions`</mark> query to track individual execution statuses.
{% endhint %}
## Trigger Order Dependencies
**Price triggers** can optionally depend on other orders being filled first. This allows creating complex order chains where one trigger only activates after another order executes.
**Dependency Configuration:**
```json
{
"trigger": {
"price_trigger": {
"price_requirement": {
"oracle_price_above": "50000000000000000000000"
},
"dependency": {
"digest": "0x1234567890abcdef1234567890abcdef12345678",
"on_partial_fill": false
}
}
}
}
```
**Parameters:**
* <mark style="color:red;">`digest`</mark>: The order digest (32-byte hex string) that must be filled before this trigger activates
* <mark style="color:red;">`on_partial_fill`</mark>:
* `true`: Trigger activates when the dependency order is partially filled
* `false`: Trigger only activates when the dependency order is completely filled
**Important Notes:**
* Dependencies are **only supported for price triggers**, not TWAP orders
* Dependency orders can be regular orders or other trigger orders
* Circular dependencies are not allowed
* If a dependency order is cancelled, the dependent trigger order is also cancelled
**Use Cases:**
* **Take profit after stop loss**: Set a take profit order that only triggers after a stop loss executes
* **Scaling strategies**: Execute multiple orders in sequence based on fills
* **Complex exit strategies**: Chain multiple conditional exits together
## Constructing Order Appendix
{% hint style="warning" %}
**CRITICAL**: The order <mark style="color:red;">`appendix`</mark> field must be correctly configured for trigger orders. The appendix is a 128-bit integer sent as a string.
{% endhint %}
### Using Python SDK (Recommended)
```python
from nado_protocol.utils.appendix import build_appendix
from nado_protocol.utils.appendix import OrderAppendixTriggerType
# Price trigger order
appendix = build_appendix(
order_type=0, # DEFAULT
trigger_type=OrderAppendixTriggerType.PRICE
)
# Result: "4096"
# TWAP order: 5 executions, 1% slippage (must use IOC)
appendix = build_appendix(
order_type=1, # IOC (required for TWAP)
trigger_type=OrderAppendixTriggerType.TWAP,
twap_times=5,
twap_slippage_frac=0.01
)
# Result: "21474841600"
```
### Manual Bit Manipulation
```python
def build_trigger_appendix(trigger_type, order_type=0, twap_times=0, twap_slippage_frac=0.0):
appendix = 0
# Version (bits 0-7): Always 0
appendix |= 0
# Order type (bits 9-10): 0=DEFAULT, 1=IOC (required for TWAP)
appendix |= (order_type & 0b11) << 9
# Trigger type (bits 12-13): 1=PRICE, 2=TWAP, 3=TWAP_CUSTOM_AMOUNTS
appendix |= (trigger_type & 0b11) << 12
# TWAP configuration in value field (bits 32-127)
if trigger_type == 2 or trigger_type == 3: # TWAP or TWAP_CUSTOM_AMOUNTS
slippage_x6 = int(twap_slippage_frac * 1_000_000)
value = (twap_times & ((1 << 32) - 1)) | ((slippage_x6 & ((1 << 32) - 1)) << 32)
appendix |= (value & ((1 << 96) - 1)) << 32
return str(appendix)
# Examples:
price_appendix = build_trigger_appendix(1) # Price trigger
# Result: "4096"
twap_appendix = build_trigger_appendix(2, 1, 5, 0.01) # TWAP: IOC, 5 times, 1% slippage
# Result: "21474841600"
twap_custom = build_trigger_appendix(3, 1, 10, 0.005) # TWAP_CUSTOM_AMOUNTS: IOC, 10 times, 0.5% slippage
# Result: "42949678080"
```
{% hint style="info" %}
**Important constraints:**
* TWAP orders **must** use IOC (order\_type=1) execution
* TWAP orders **cannot** be combined with isolated margin
* For complete appendix encoding specification, see [Order Appendix](https://docs.nado.xyz/developer-resources/api/order-appendix) documentation
{% endhint %}
## Response
#### Success
```json
{
"status": "success",
"signature": {signature},
"data": {
"digest": {order digest}
},
"request_type": "execute_place_order"
"id": 100
}
```
#### Failure
```json
{
"status": "failure",
"signature": {signature},
"error": "{error_msg}",
"error_code": {error_code},
"request_type": "execute_place_order"
}
```
@@ -0,0 +1,179 @@
# Place Orders
Place multiple trigger orders in a single request. This is more efficient than placing orders individually and allows for better control over batch trigger order placement.
## Rate limits
* A max of 25 pending trigger orders per product per subaccount
{% hint style="info" %}
See more details in [Trigger Service Limits](https://docs.nado.xyz/developer-resources/rate-limits#trigger-service-limits).
{% endhint %}
{% hint style="warning" %}
**Important**: All orders in a batch must belong to the same subaccount. Orders with different senders will be rejected.
{% endhint %}
## Request
<mark style="color:orange;">`POST [TRIGGER_ENDPOINT]/execute`</mark>
### Body
```json
{
"place_orders": {
"orders": [
{
"product_id": 2,
"order": {
"sender": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
"priceX18": "100000000000000000000000",
"amount": "1000000000000000000",
"expiration": "4294967295",
"nonce": "1757062078359666688",
"appendix": "4096"
},
"trigger": {
"price_trigger": {
"price_requirement": {
"oracle_price_below": "100000000000000000000000"
}
}
},
"signature": "0x...",
"id": 100
},
{
"product_id": 3,
"order": {
"sender": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
"priceX18": "3800000000000000000000",
"amount": "2000000000000000000",
"expiration": "4294967295",
"nonce": "1757062078359666689",
"appendix": "4096"
},
"trigger": {
"price_trigger": {
"price_requirement": {
"oracle_price_above": "3800000000000000000000"
}
}
},
"signature": "0x...",
"id": 101
}
],
"stop_on_failure": false
}
}
```
## Request Parameters
<table><thead><tr><th width="200" align="center">Parameter</th><th width="94" align="center">Type</th><th width="112" align="center">Required</th><th>Description</th></tr></thead><tbody><tr><td align="center">orders</td><td align="center">array</td><td align="center">Yes</td><td>Array of trigger order objects to place. Each order follows the same structure as <a href="place-order">Place Order</a>. <strong>All orders must have the same sender</strong>.</td></tr><tr><td align="center">orders[].product_id</td><td align="center">number</td><td align="center">Yes</td><td>Id of spot / perp product for which to place order.</td></tr><tr><td align="center">orders[].order</td><td align="center">object</td><td align="center">Yes</td><td>Order object (same structure as single order placement).</td></tr><tr><td align="center">orders[].trigger</td><td align="center">object</td><td align="center">Yes</td><td>Trigger criteria - either price_trigger or time_trigger. See <a href="place-order">Place Order</a> for details.</td></tr><tr><td align="center">orders[].signature</td><td align="center">string</td><td align="center">Yes</td><td>Hex string representing hash of the <strong>signed</strong> order.</td></tr><tr><td align="center">orders[].digest</td><td align="center">string</td><td align="center">No</td><td>Hex string representing a hash of the order.</td></tr><tr><td align="center">orders[].spot_leverage</td><td align="center">boolean</td><td align="center">No</td><td>Indicates whether leverage should be used for this order. Defaults to <mark style="color:red;"><code>true</code></mark>.</td></tr><tr><td align="center">orders[].id</td><td align="center">number</td><td align="center">No</td><td>An optional id returned in <mark style="color:red;"><code>Fill</code></mark> and <mark style="color:red;"><code>OrderUpdate</code></mark> events.</td></tr><tr><td align="center">stop_on_failure</td><td align="center">boolean</td><td align="center">No</td><td>If <mark style="color:red;"><code>true</code></mark>, stops processing remaining orders when the first order fails. Already successfully placed orders are NOT cancelled. Defaults to <mark style="color:red;"><code>false</code></mark>.</td></tr></tbody></table>
## Response
```json
{
"status": "success",
"data": {
"place_orders": [
{
"digest": "0x1234...",
"error": null
},
{
"digest": null,
"error": "Max trigger orders limit reached"
}
]
}
}
```
### Response Fields
<table><thead><tr><th width="200">Field</th><th>Description</th></tr></thead><tbody><tr><td>digest</td><td>Order digest (32-byte hash) if successfully placed, <mark style="color:red;"><code>null</code></mark> if failed.</td></tr><tr><td>error</td><td>Error message if order failed, <mark style="color:red;"><code>null</code></mark> if successful.</td></tr></tbody></table>
## Behavior
* **Partial Success**: By default, orders are processed independently. Some orders may succeed while others fail.
* **Stop on Failure**: Set `stop_on_failure: true` to stop processing remaining orders when the first order fails. Already successfully placed orders remain active.
* **Same Sender Required**: All orders in a batch must have the same sender. Mixed sender batches will be rejected with `BatchSenderMismatch` error.
* **Order Signing**: Each order must be individually signed using EIP712 (see [Signing](https://github.com/nadohq/nado-docs/blob/main/docs/developer-resources/api/gateway/executes/signing/README.md) for details).
* **Per-Order Limits**: The 25 pending trigger orders per product per subaccount limit applies to each order individually.
## Use Cases
* **Multi-Market Stop Losses**: Set stop loss triggers across multiple products simultaneously
* **Bracket Orders**: Place both take profit and stop loss triggers together
* **Conditional Exits**: Create multiple exit strategies across different products
## Example
Placing stop loss triggers for BTC and ETH perps:
```javascript
const placeTriggerOrdersParams = {
orders: [
{
product_id: 2, // BTC-PERP
order: {
sender: subaccount,
priceX18: toX18(95000), // Stop at $95k
amount: toX18(-0.1), // Sell 0.1 BTC
expiration: getExpiration(OrderType.DEFAULT),
nonce: genOrderNonce(),
appendix: buildAppendix({
order_type: 0,
trigger_type: OrderAppendixTriggerType.PRICE
})
},
trigger: {
price_trigger: {
price_requirement: {
oracle_price_below: toX18(95000)
}
}
},
signature: await signOrder(btcOrder),
id: 1
},
{
product_id: 3, // ETH-PERP
order: {
sender: subaccount, // Must be same sender
priceX18: toX18(3600), // Stop at $3.6k
amount: toX18(-1), // Sell 1 ETH
expiration: getExpiration(OrderType.DEFAULT),
nonce: genOrderNonce(),
appendix: buildAppendix({
order_type: 0,
trigger_type: OrderAppendixTriggerType.PRICE
})
},
trigger: {
price_trigger: {
price_requirement: {
oracle_price_below: toX18(3600)
}
}
},
signature: await signOrder(ethOrder),
id: 2
}
],
stop_on_failure: false
};
const response = await triggerClient.execute({ place_orders: placeTriggerOrdersParams });
```
## See Also
* [Place Order](https://docs.nado.xyz/developer-resources/api/trigger/executes/place-order) - Single trigger order placement
* [Cancel Orders](https://docs.nado.xyz/developer-resources/api/trigger/executes/cancel-orders) - Cancel multiple trigger orders
* [List Trigger Orders](https://docs.nado.xyz/developer-resources/api/trigger/queries/list-trigger-orders) - Query active trigger orders