Smart Accounts and signing
A Smart Account holds a user's collateral and positions. The owner wallet funds it, withdraws funds and manages signing keys.
An intent is a signed trading instruction. The SDK prepares it and signs it with a registered Ed25519 key. Storm checks the instruction, groups it into a bundle and sends it to the blockchain.
Use V3 for new integrations. V2 sends transactions directly from the user's TON wallet.
Query IDs
Every new order needs an unused query ID for its Smart Account:
- Read a starting value with
getQueryID. - Reserve and save the ID in your application before signing. Coordinate this across all processes and devices using the account.
- For attached SL/TP, reserve one extra ID per trigger. The JS SDK assigns those IDs consecutively after the opening order.
The lookup does not reserve an ID, and the JS SDK does not manage the counter. IDs range from 0 to 8,380,415. Signed cancellations need no new ID. A user intent ID and a bundle's execution ID are different identifiers.
If a request times out, check its saved hash before creating another order. Reusing a consumed ID returns QUERY_ID_ALREADY_USED.
Confirm execution
Save the signed request and all intent hashes before sending. Check the intent, find its account bundle, then confirm the outcome through transactions and account state.
| Bundle status | Meaning |
|---|---|
pending | Collecting instructions |
sealed | Ready to send |
sent | Sent to the blockchain |
confirmed | Succeeded on-chain |
failed | Failed on-chain |
An intent marked accepted or done does not prove a fill. A placed limit or stop order may still be waiting to execute. If the intent record has expired, check indexed history.
Amounts and time
| Value | Unit |
|---|---|
| V3 order collateral, margin, price, leverage and position size | 9 decimals; use toNano('1.5') for 1.5 |
| Deposits, withdrawals and V2 collateral | Token decimals: 6 for USDT, 9 for TON |
Intent createdAt and order expiration | Unix seconds |
Keep large integers as strings or bigint. Follow each endpoint's schema for timestamps returned by reads. Find market vAMM addresses in markets.
Fees
Trading Fees apply when opening and closing positions. Execution Fee and funding are separate and do not generate builder payouts. See Builder Fees and Trading Fees.
Errors
| Error | Action |
|---|---|
EMULATE_ERROR | Check the contract exit code and correct the order |
NOT_ENOUGH_BALANCE | Add collateral or reduce the order |
QUERY_ID_ALREADY_USED | Check the earlier intent before reserving another ID |
The JS SDK throws V3ApiError with status and body when submission is rejected, including an HTTP 200 response without acceptance. A network error can leave the result unknown. Check the saved hash; the SDK does not retry automatically.