> For the complete documentation index, see [llms.txt](https://docs.dimes.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dimes.fi/for-developers/getting-started/sdk-installation.md).

# SDK Installation

### Install

```bash
npm install @dimes-dot-fi/sdk
```

### Entry points

The SDK ships four entry points. Import only what you need — peer dependencies are optional.

| Entry point                  | What it provides                                        | Peer dependencies                         |
| ---------------------------- | ------------------------------------------------------- | ----------------------------------------- |
| `@dimes-dot-fi/sdk`          | HTTP client, quote engine, error types                  | None                                      |
| `@dimes-dot-fi/sdk/react`    | React hooks and context provider                        | `react >=19`, `@tanstack/react-query >=5` |
| `@dimes-dot-fi/sdk/contract` | On-chain transaction builders, signature verification   | `viem >=2`                                |
| `@dimes-dot-fi/sdk/ws`       | WebSocket clients for the user position/market gateways | None (`socket.io-client` is bundled)      |

Install peer dependencies for the entry points you use:

```bash
# React hooks
npm install react @tanstack/react-query

# On-chain integration
npm install viem
```

***

### Client setup

{% tabs %}
{% tab title="API Key (server-side)" %}
Use `ApiKeyAuth` when your backend holds the API key and generates JWTs for users.

```typescript
import { DimesClient, ApiKeyAuth } from "@dimes-dot-fi/sdk";

const client = new DimesClient({
  auth: new ApiKeyAuth({
    apiKey: process.env.DIMES_API_KEY,
    walletAddress: "0x1234...abcd",
  }),
});

const markets = await client.getMarkets();
```

`ApiKeyAuth` automatically obtains and refreshes JWTs.
{% endtab %}

{% tab title="JWT (client-side)" %}
Your backend holds the Dimes API key and exposes an endpoint that generates JWTs for your users. Point `JwtAuth` at that endpoint — it fetches, caches, and auto-refreshes tokens:

```typescript
import { DimesClient, JwtAuth } from "@dimes-dot-fi/sdk";

const client = new DimesClient({
  auth: new JwtAuth({ tokenUrl: "https://your-backend.com/api/dimes-token" }),
});

const markets = await client.getMarkets();
```

Your backend endpoint should call `POST /v1/prediction-markets/tokens` with your API key and return the `{ token, expires_at }` response. See [Authentication](/for-developers/api-and-events/authentication.md).
{% endtab %}

{% tab title="React" %}
Wrap your app in `DimesProvider` to use hooks.

```tsx
import { DimesClient, JwtAuth } from "@dimes-dot-fi/sdk";
import { DimesProvider } from "@dimes-dot-fi/sdk/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();

const client = new DimesClient({
  auth: new JwtAuth({ tokenUrl: "https://your-backend.com/api/dimes-token" }),
});

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <DimesProvider client={client}>
        <YourApp />
      </DimesProvider>
    </QueryClientProvider>
  );
}
```

Hooks use whatever `QueryClientProvider` is in your React tree. See [React Hooks](/for-developers/getting-started/react-hooks.md) for the full set — data hooks, the `useQuote` / `useQuoteMachine` quote flows, and the live `usePositionStream` / `useMarketStream` WebSocket hooks.
{% endtab %}
{% endtabs %}

***

### Sandbox

Point the client at sandbox by passing `baseUrl`:

```typescript
const client = new DimesClient({
  baseUrl: "https://api-sandbox.dimes.fi",
  auth: new ApiKeyAuth({
    apiKey: "dm_sbx_skey_...",
    walletAddress: "0x...",
  }),
});
```

See [Sandbox](/for-developers/getting-started/sandbox.md) for how to get a sandbox key and test pUSD.

***

### Custom fetch

Pass a custom `fetch` implementation for environments without a global `fetch` (older Node.js, test mocks, etc.):

```typescript
import { DimesClient, JwtAuth } from "@dimes-dot-fi/sdk";
import fetch from "node-fetch";

const client = new DimesClient({
  auth: new JwtAuth({ tokenUrl: "https://your-backend.com/api/dimes-token" }),
  fetch: fetch as unknown as typeof globalThis.fetch,
});
```

***

### Helpers

The core entry point also exports framework-agnostic helpers for the math behind market and position UIs, so you don't reimplement it from raw fields:

| Helper                                                                     | Use                                                         |
| -------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `getSidedEligibility(market)`                                              | Per-side (yes/no) tradeability, caps, and rejection reasons |
| `defaultSide(eligibility)`                                                 | The side to preselect in a trade panel                      |
| `leverageMaxBps(leverage, side)`                                           | Max leverage for a side                                     |
| `maxLeverageBpsAtNotional(...)` / `maxViableLeverageBpsForCollateral(...)` | Notional/collateral-aware leverage ceilings                 |
| `estimateLiquidationPrice(...)`                                            | Liquidation price for an open position                      |
| `computeMaxGain(input)`                                                    | Gross/net max gain for a quote                              |
| `getOriginationFeeBreakdown(...)`                                          | Protocol/partner origination fee split                      |
| `computePolymarketTradingFee(...)`                                         | Venue trading fee                                           |
| `isOpenPosition(p)` / `isClosedPosition(p)`                                | Narrow a `Position` union                                   |
| `rejectionReasonText(...)` / `rejectionReasonShort(...)`                   | Human-readable ineligibility messages                       |

These power the same displays in the reference UI — prefer them over hand-rolling fee/leverage/liquidation math.

***

### What's next

* [Quickstart](/for-developers/getting-started/quickstart.md) — end-to-end integration in 6 steps
* [React Hooks](/for-developers/getting-started/react-hooks.md) — data, quote, and live WebSocket hooks
* [Authentication](/for-developers/api-and-events/authentication.md) — API keys, JWTs, and key rotation
* [API Reference](/for-developers/api-and-events/api-reference.md) — full endpoint documentation