@ostium/builder-sdk 0.1.0 → 0.2.0

package/README.md

@@ -113,6 +113,55 @@ const client = await OstiumClient.createDelegatedAndGasless({
 });
 ```
 
+### Build Unsigned Transactions
+
+Every write method now has a `get*Tx()` counterpart that returns transaction
+data without signing or submitting it.
+
+```ts
+const client = await OstiumClient.createSelfAndSelf({
+  traderAddress: '0xTraderAddress',
+});
+
+const tx = client.getOpenTradeTx({
+  pairId: 0,
+  buy: true,
+  price: '65000',
+  collateral: '100',
+  leverage: '5',
+  type: OrderType.Market,
+});
+
+if (tx.kind === 'eoa') {
+  await window.ethereum.request({
+    method: 'eth_sendTransaction',
+    params: [{
+      from: tx.from,
+      to: tx.to,
+      data: tx.data,
+      value: `0x${tx.value.toString(16)}`,
+    }],
+  });
+}
+```
+
+Gasless build-only clients return a Safe-style request instead:
+
+```ts
+const gaslessClient = await OstiumClient.createSelfAndGasless({
+  traderAddress: '0xTraderAddress',
+  safeAddress: '0xSafeAddress',
+});
+
+const safeTx = gaslessClient.getOpenTradeTx({ ... });
+// safeTx.kind === 'safe'
+// safeTx.safeAddress identifies the Safe that should execute safeTx.calls[0]
+```
+
+The existing write methods (`openTrade`, `closeTrade`, `approveUsdc`, etc.)
+still work the same way, but they now submit the transaction built by the
+corresponding `get*Tx()` method.
+
 ### Read-only (no private key)
 
 Use `createReadOnly` to access market data without a signer. All read methods are available; write methods throw `INVALID_CONFIG`.
@@ -124,6 +173,27 @@ const positions = await reader.getOpenPositions({ user: '0xTrader...' });
 const balances = await reader.getBalances('0xTrader...');
 ```
 
+### Stream Position Updates
+
+If you already have an `OpenPositionsResponse`, you can stream live price-driven
+updates for those positions without re-fetching the full position set.
+
+```ts
+const positions = await client.getOpenPositions();
+const stream = client.streamPositionUpdates(positions);
+
+stream.onUpdate(next => {
+  console.log(next.marginSummary.totalRawPnlUsd);
+  console.log(next.pairPositions[0]?.position.unrealizedPnl);
+});
+
+stream.onError(err => console.error(err));
+stream.close();
+```
+
+The SDK subscribes once per unique `pairId` in the response, then updates the
+full `OpenPositionsResponse` as prices change.
+
 ### Common Options
 
 All constructors (including `createReadOnly`) accept these optional overrides:
@@ -279,7 +349,7 @@ Use `getOrders({ initiatedTxHashes: [result.txHash] })` to poll by submission ha
 
 ```ts
 const result = await client.openTrade({
-  pairIndex:   0,                  // trading pair (use getPairs() to list all)
+  pairId:      0,                  // trading pair (use getPairs() to list all)
   buy:         true,               // true = long, false = short
   price:       '65000',            // entry price
   collateral:  '100',              // USD (min $5)
@@ -408,7 +478,7 @@ const { prices } = await client.getAllPrices();
 Open positions, margin summary, and per-position live PnL. Block number is fetched automatically on `OstiumClient`.
 
 ```ts
-const { pairPositions, marginSummary, withdrawable, time } =
+const { pairPositions, marginSummary, time } =
   await client.getOpenPositions();
 
 // Each position:
@@ -418,7 +488,7 @@ const { pairId, pid, idx, side, szi, entryPx, leverage, ntl,
         openTimestamp, isDayTrade } = pairPositions[0].position;
 
 // marginSummary: accountValue, totalCollateralUsed, totalNtlPos, totalRawPnlUsd
-// withdrawable: max collateral removable across all positions
+// marginSummary.totalWithdrawable: max collateral removable across all positions
 // time: server time (Unix ms)
 ```