# SDK Installation

### Install

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

### Entry points

The SDK ships three 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`                                |

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/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 — they work with your existing TanStack Query setup.
{% 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/sandbox.md) for how to get a sandbox key and fake USDC.

***

### 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,
});
```

***

### What's next

* [Quickstart](/for-developers/quickstart.md) — end-to-end integration in 6 steps
* [Authentication](/for-developers/authentication.md) — API keys, JWTs, and key rotation
* [API Reference](/for-developers/api-reference.md) — full endpoint documentation


---

# Agent Instructions: 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.dimes.fi/for-developers/sdk-installation.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.