@thetanuts-finance/odette-sdk 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +49 -119
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,125 +1,28 @@
1
- # Odette SDK and CLI
1
+ # Odette SDK
2
2
 
3
- Buy Odette options on Base from your terminal or your own code.
3
+ Buy Odette options on Base from your own code: trading bots, apps, scripts and AI agents.
4
4
 
5
- - **`odette`**, the command-line tool: `@thetanuts-finance/odette-cli`
6
- - **The SDK**, a TypeScript library: `@thetanuts-finance/odette-sdk`
5
+ Just want to trade from a terminal? Use the CLI,
6
+ [`@thetanuts-finance/odette-cli`](https://www.npmjs.com/package/@thetanuts-finance/odette-cli).
7
7
 
8
- Odette runs on Thetanuts Finance contracts on Base. You sign every trade with your
9
- own wallet. No trade goes through a server: `odette` only reads the public order
10
- list and sends your signed transaction straight to Base.
8
+ The SDK reads the public order list, then calls the OptionBook contract on Base
9
+ (`fillOrder`) with your own signer. You don't need to know the contract: the SDK
10
+ handles the order format, sizing and units, safety checks and approvals.
11
+ **Every fill carries Odette's referrer**, `0x94D784e81A5c8cA6E19629C73217b61a256Ea1c7`.
12
+ It is fixed; no option changes it.
11
13
 
12
- ## What you can do
13
-
14
- - See the options Odette lists right now: PUT, CALL (LINEAR_CALL) and RANGER.
15
- - Check a trade before you make it.
16
- - Buy an option with USDC.
17
-
18
- The tools only **buy**. They do not sell or close positions. Odette options are
19
- cash-settled in USDC at expiry, so there is nothing to close.
20
-
21
- ## Before you start
22
-
23
- - [Node.js](https://nodejs.org) 20 or newer
24
- - A wallet on **Base** with:
25
- - **USDC**, to pay for the option (the minimum trade is 0.50 USDC)
26
- - a little **ETH**, for gas (a trade costs a few cents)
14
+ Products: PUT, CALL (LINEAR_CALL) and RANGER, paid in USDC. The SDK only **buys**.
15
+ Odette options are cash-settled in USDC at expiry.
27
16
 
28
17
  ## Install
29
18
 
30
19
  ```sh
31
- npm install -g @thetanuts-finance/odette-cli
32
- ```
33
-
34
- ## Set up your wallet (once)
35
-
36
- Use the wallet you already have:
37
-
38
- ```sh
39
- odette wallet import
40
- ```
41
-
42
- Paste your private key when asked. You won't see it as you paste, and that's expected.
43
-
44
- Don't have one? `odette wallet create` makes a new wallet. Then send it USDC and some ETH on Base.
45
-
46
- Your key is saved only on your computer, in `~/.config/odette/config.json`, and only you
47
- can read that file. **Never share your private key or paste it into a chat.**
48
-
49
- Check it worked:
50
-
51
- ```sh
52
- odette wallet show # your address
53
- odette wallet balance # your ETH and USDC
54
- ```
55
-
56
- ## Make a trade
57
-
58
- **1. See what's on offer.**
59
-
60
- ```sh
61
- odette orders --underlying ETH --type PUT
62
- ```
63
-
64
- Each row is one option: its strike price, the expiry date and time, and the price of one contract.
65
- `--type` can be `PUT`, `CALL` or `RANGER`.
66
-
67
- **2. Check the trade.** Pick a strike and expiry from the list. `--collateral` is how
68
- much USDC you want to spend. (The strike and expiry below are examples: copy real
69
- ones from `odette orders`, because options expire every day.)
70
-
71
- ```sh
72
- odette preview --underlying ETH --type PUT --strike 2200 --expiry 1793174400 --collateral 5
73
- ```
74
-
75
- This shows how many contracts you get, and runs safety checks:
76
- does the seller have the funds, do you have enough USDC, is the quote still live.
77
- Nothing is sent.
78
-
79
- **3. Buy.**
80
-
81
- ```sh
82
- odette fill --underlying ETH --type PUT --strike 2200 --expiry 1793174400 --collateral 5
83
- ```
84
-
85
- The first time, `odette` asks you to let the Odette contract take your USDC. That
86
- permission is called an approval. Then it asks you to confirm the trade. Answer `y`
87
- to both. When it's done, it prints the transaction link.
88
-
89
- Prices update about once a minute. If the price moves while you're deciding, `odette`
90
- shows the new price and asks you again.
91
-
92
- Want to see the transaction without sending it? Add `--dry-run`. With `--yes` (no
93
- questions), `--collateral` is required, so `odette` never buys a maximum size by itself.
94
-
95
- **Buying a RANGER.** A RANGER pays out if the price ends inside a range. It has
96
- four strikes, so use `--type RANGER` with `--strikes`:
97
-
98
- ```sh
99
- odette orders --underlying BTC --type RANGER
100
- odette preview --underlying BTC --type RANGER --strikes 78500,79000,80000,80500 --expiry 1793174400 --collateral 5
20
+ npm install @thetanuts-finance/odette-sdk ethers
101
21
  ```
102
22
 
103
- `preview` shows what you pay (`premium`) and the most you can be paid at expiry (`maxPayout`). In `-o json`
104
- output the premium is the `totalCollateral` field (the name upstream uses).
105
-
106
- ## Useful flags
23
+ Node.js 20 or newer, ethers v6. ESM and CommonJS both work.
107
24
 
108
- | Flag | What it does |
109
- |---|---|
110
- | `--dry-run` | Show what would happen. Send nothing. |
111
- | `--yes` | Skip the questions (the safety checks still run). |
112
- | `-o json` | Print JSON, for scripts. |
113
- | `--rpc-url <url>` | Use your own Base RPC instead of the public one. |
114
-
115
- Exit codes for scripts: `0` ok, `1` the trade or a check failed, `2` a wrong command or flag,
116
- `3` you said no, `4` a wallet or config problem.
117
-
118
- ## For developers: the SDK
119
-
120
- ```sh
121
- npm install @thetanuts-finance/odette-sdk ethers
122
- ```
25
+ ## Quick start
123
26
 
124
27
  ```ts
125
28
  import { JsonRpcProvider, Wallet } from 'ethers';
@@ -137,21 +40,48 @@ const preview = client.optionBook.previewFillOrder(order, usdc);
137
40
  const checks = await client.optionBook.checkFill(order, usdc); // reads only, never sends
138
41
 
139
42
  await client.erc20.ensureAllowance(preview.collateralToken, preview.optionBook, preview.totalCollateral);
140
- const receipt = await client.optionBook.fillOrder(order, usdc); // refuses if a check fails
43
+ const receipt = await client.optionBook.fillOrder(order, usdc, {
44
+ onSent: (hash) => console.log('sent', hash), // the tx hash, before it is mined
45
+ });
46
+ console.log(client.optionBook.decodeOrderFilled(receipt));
141
47
  ```
142
48
 
143
- Amounts: USDC and contract sizes have 6 decimals. Prices and strikes are in USD with 8 decimals.
144
- The amount you pass is the USDC you want to spend, not a number of contracts.
49
+ ## Main methods
50
+
51
+ | Method | What it does |
52
+ |---|---|
53
+ | `new OdetteClient({ provider, signer? })` | Base (8453) only. Refuses a `referrer` option. |
54
+ | `client.api.fetchOrders()` | The orders the Odette app lists now (PUT, LINEAR_CALL, RANGER). |
55
+ | `client.optionBook.previewFillOrder(order, usdc?)` | Contracts, premium (`totalCollateral`), `maxPayout`, step, min, max. No network. |
56
+ | `client.optionBook.checkFill(order, usdc?)` | The pre-send checks against Base: chain, order, size, maker funds, your balance and allowance, simulation. Never sends. |
57
+ | `client.optionBook.encodeFillOrder(order, usdc?)` | `{ to, data }` for any wallet library (for example a smart wallet). |
58
+ | `client.optionBook.fillOrder(order, usdc?, { onSent? })` | Runs the checks, then sends `fillOrder`. Refuses to send if a check fails. |
59
+ | `client.optionBook.decodeOrderFilled(receipt)` | The `OrderFilled` event: option address, premium, fee, referrer. |
60
+ | `client.erc20.ensureAllowance(token, spender, amount)` | Approves USDC if needed. |
61
+
62
+ Without `usdc`, preview, encode and fill use the order's **maximum** size.
63
+
64
+ ## Units
65
+
66
+ - USDC amounts and contract sizes have 6 decimals (`5_000000n` = 5 USDC).
67
+ - Prices and strikes are USD with 8 decimals.
68
+ - The amount you pass is the USDC premium you want to spend, not a number of
69
+ contracts. Sizes round down to the contract's step; the minimum premium is 0.50 USDC.
70
+
71
+ ## Errors
72
+
73
+ Errors are `OdetteError` with a `code`, for example `CHECK_FAILED`, `SIGNER_REQUIRED`,
74
+ `INVALID_ORDER` or `TRANSACTION_CANCELLED`. A fill that was sent never reports as failed
75
+ because of a callback or a logger.
145
76
 
146
77
  ## Good to know
147
78
 
148
79
  - **Base only** (chain 8453).
149
- - **Found a security problem?** Don't open a public issue. See `SECURITY.md`.
150
- - **Every trade is tagged with Odette's referrer**, `0x94D784e81A5c8cA6E19629C73217b61a256Ea1c7`.
151
- You can't change it in these tools. The contract itself does not enforce the tag.
152
- - Orders and contracts come from Thetanuts Finance. Odette is the app on top.
80
+ - The contracts and the order feed are Thetanuts Finance's. Odette is the app on top.
81
+ - The referrer tag is a default in this SDK, not enforced by the contract.
82
+ - **Found a security problem?** Don't open a public issue. See [SECURITY.md](https://github.com/Shawnchee/odette-sdk/blob/main/SECURITY.md).
153
83
 
154
84
  ## License
155
85
 
156
86
  MIT, Copyright (c) 2026 Thetanuts Finance. Parts are adapted from
157
- [thetanuts-sdk](https://github.com/Thetanuts-Finance/thetanuts-sdk); see `NOTICE.md`.
87
+ [thetanuts-sdk](https://github.com/Thetanuts-Finance/thetanuts-sdk); see [NOTICE.md](https://github.com/Shawnchee/odette-sdk/blob/main/NOTICE.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@thetanuts-finance/odette-sdk",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Odette SDK. Read the Odette order book and buy Odette options on Base with your own signer.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",