> For the complete documentation index, see [llms.txt](https://docs.turbine.exchange/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.turbine.exchange/reference/api/turbine-sdk.md).

# Turbine SDK

The Turbine SDK is the official TypeScript client. It wraps every Turbine HTTP endpoint and handles SIWE authentication for you. The Turbine frontend uses this same SDK.

#### Versions

<table data-header-hidden><thead><tr><th width="157"></th><th width="413"></th></tr></thead><tbody><tr><td><strong>Node version</strong></td><td>18 or later</td></tr><tr><td><strong>SDK version</strong></td><td><strong>0.26.0 or later.</strong> 0.26.0 reads the new response shape where the backend returns <code>spreadCurve</code> instead of <code>midPriceDelta</code>. 0.25.0 introduced <code>spreadCurve</code> on the order intent but still expected <code>midPriceDelta</code> in responses, so it fails to parse responses against current backends.</td></tr><tr><td><strong>Backend version</strong></td><td>Read live from <code>GET /api/config</code>. As of 2026-05-20: dev returns <code>0.112.0</code>, staging <code>0.111.1</code>, production older (no <code>version</code> field yet).</td></tr><tr><td><strong>Wire format</strong></td><td>camelCase everywhere, both top-level and nested.</td></tr></tbody></table>

#### Install

```
yarn add turbine-sdk
# or
npm install turbine-sdk
```

#### Authentication

The SDK handles SIWE authentication automatically via `TurbineClient.ensureAuthenticated()`. See [Authentication](/reference/api/authentication.md) for the underlying flow if you implement it yourself.

### Dynamic spread

Turbine orders track the market mid-price at a spread you choose. That spread can change over the life of the order. The shape of that spread over time is a `SpreadCurve`. This section covers the type, the SDK helpers, the HTTP endpoints, validation, and migration from the legacy `midPriceDelta` field.

#### The SpreadCurve type

The curve is piecewise-linear:

```
type SpreadCurve = {
  startDeltaBps: number;  // i32, in [-10_000, 10_000)
  endDeltaBps:   number;  // i32, in [-10_000, 10_000)
  points: CurvePoint[];   // optional interior knots, strictly increasing windowBps
};

type CurvePoint = {
  windowBps: number;  // u32, in (0, 10_000): fraction of order lifetime, in bps
  deltaBps:  number;  // i32, in [-10_000, 10_000)
};
```

#### Constraints

| Rule                                       | Limit                                     |
| ------------------------------------------ | ----------------------------------------- |
| Spread delta range                         | `-10000` to `9999` bps (about ±100%)      |
| Window range (interior knots)              | `1` to `9999` bps of the order's lifetime |
| Window monotonicity                        | Strictly increasing                       |
| Max interior points                        | 1024                                      |
| `midPriceDelta` and `spreadCurve` together | Rejected. Set exactly one.                |

Precision is basis points (0.01%). Anything finer is rounded down at submission. Pass `2` or `3`, not `0.021%`.

**Sign convention.** Positive bps = worse-than-mid (the user pays). Negative bps = better-than-mid (the order only fills if the market crosses in the user's favor).

#### SDK helpers

**Constant spread**

Drop-in replacement for the old `midPriceDelta`:

```
import { OrderIntent } from "turbine-sdk/models";
import * as spreads from "turbine-sdk/spreads";

const intent: OrderIntent = {
  spreadCurve: spreads.constant(10), // 0.1% spread for the entire order
  // ...rest of the order
};
```

**Auto (what the frontend Auto toggle uses)**

```
const intent: OrderIntent = {
  spreadCurve: spreads.auto({
    fastSpreadBps: 10,   // average market spread for the pair, in basis points
    // deltaBps: 2,      // optional. default = max(1, round(fastSpreadBps * 0.2))
    // yoloBps: -1000,   // optional. default = -1000
  }),
};
```

The helper returns a four-knot piecewise-linear curve with anchors at:

| windowBps | deltaBps                   |
| --------- | -------------------------- |
| `0`       | `yoloBps`                  |
| `1000`    | `-fastSpreadBps`           |
| `5000`    | `fastSpreadBps - deltaBps` |
| `10000`   | `fastSpreadBps + deltaBps` |

The endpoint is `fastSpreadBps + deltaBps`; the `deltaBps` term is the small safety buffer that absorbs block-to-block AMM fluctuations.

The helper throws if any of these monotonicity rules break:

* `yoloBps` must be strictly less than `-fastSpreadBps`.
* `deltaBps` must be strictly less than `2 × fastSpreadBps`.
* `fastSpreadBps + deltaBps` must not exceed `MAX_DELTA_BPS` (= 9999).

**Custom piecewise-linear curve**

```
const intent: OrderIntent = {
  spreadCurve: {
    startDeltaBps: -1000,
    endDeltaBps: 10,
    points: [
      { windowBps: 1000, deltaBps: -10 },   // by 10% into the order, reach mid
      { windowBps: 5000, deltaBps: 5 },     // halfway, sit at 0.05%
    ],
  },
};
```

#### HTTP API

**POST /api/add\_order**

Accepts `spreadCurve` or the legacy `midPriceDelta` on the request body. They are mutually exclusive. `midPriceDelta` is deprecated and will be removed from the request schema in a future release; it is already removed from the SDK type and from `GET /api/orders` responses as of SDK 0.26.0.

```
{
  "spreadCurve": {
    "startDeltaBps": -1000,
    "endDeltaBps": 10,
    "points": [
      { "windowBps": 5000, "deltaBps": 0 }
    ]
  },
  "...": "..."
}
```

**GET /api/orders**

Returns `spreadCurve` on each `OrderDetails`. The legacy `midPriceDelta` field is no longer in the response. If your code expects it, parsing fails. Update to SDK 0.26.0 or read `spreadCurve` directly.

**GET /api/config**

Returns the settler and LP hook addresses, signer address, and the active token allowlist with class and per-venue oracle feeds. On staging the response also includes a `version` field for the active backend; the field is not yet present on production. Read this before bumping the SDK to confirm compatibility.

#### Validation errors

| Error                      | Meaning                                                                  |
| -------------------------- | ------------------------------------------------------------------------ |
| `SpreadMissing`            | Neither `midPriceDelta` nor `spreadCurve` was set.                       |
| `ConflictingSpreadFields`  | Both were set. Pick one.                                                 |
| `InvalidSpreadCurve`       | A `deltaBps` is out of range, or interior `windowBps` are non-monotonic. |
| `SpreadCurveTooManyPoints` | More than 1024 interior points.                                          |

`callData` and `callDataTarget` are validated together. Set both or neither.

#### Migrating from older SDK versions

```
- midPriceDelta: 500,
+ spreadCurve: spreads.constant(500),
```

Smart-order callers that previously passed the `MID_PRICE_DELTA_MAX = 9999` sentinel:

```
- midPriceDelta: MID_PRICE_DELTA_MAX,
+ spreadCurve: spreads.constant(MID_PRICE_DELTA_MAX),
```

Smart orders now accept the full `spreadCurve` like regular orders. SDK 0.26.0 removes `midPriceDelta` from the `OrderIntent` and `OrderDetails` types; the backend still accepts `midPriceDelta` on `POST /api/add_order` for backward compatibility.

#### See also

{% content-ref url="/pages/ejRyUUm4z8T1hDAfR95n" %}
[API Specification](/reference/api/readme.md)
{% endcontent-ref %}

{% content-ref url="/pages/xKrdEO1eKeSF4zjbG3rU" %}
[Authentication](/reference/api/authentication.md)
{% endcontent-ref %}

{% content-ref url="/pages/PNYY3TrbzyTxpZ0WVpmS" %}
[Rate Limiting](/reference/api/rate-limiting.md)
{% endcontent-ref %}

#### Source

The SDK is open source at [github.com/propeller-heads/turbine-sdk](https://github.com/propeller-heads/turbine-sdk).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.turbine.exchange/reference/api/turbine-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.