SDK Installation

Install the TypeScript SDK and set up the client for server-side, browser, or React applications.

Install

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:

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

# On-chain integration
npm install viem

Client setup

Use ApiKeyAuth when your backend holds the API key and generates JWTs for users.

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.

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:

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.

Wrap your app in DimesProvider to use hooks.

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 the full set — data hooks, the useQuote / useQuoteMachine quote flows, and the live usePositionStream / useMarketStream WebSocket hooks.

Sandbox

Point the client at sandbox by passing baseUrl:

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

See Sandbox 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.):

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 — end-to-end integration in 6 steps
React Hooks — data, quote, and live WebSocket hooks
Authentication — API keys, JWTs, and key rotation
API Reference — full endpoint documentation

PreviousQuickstart NextReact Hooks

Last updated 17 days ago