Quickstart

The six-step integration path. Authenticate, list markets, quote, open, monitor, close.

Start in sandbox. Same API, same contract, test pUSD. Swap api.dimes.fi for api-sandbox.dimes.fi and use a dm_sbx_skey_... key — every example below works as-is. Working reference: dimes-demo-ui.

Using the SDK? Install it: npm install @dimes-dot-fi/sdk. See SDK Installation for setup and peer dependencies. Every SDK snippet below has a runnable, type-checked counterpart in examples/ — start with 01-quickstart.ts.

1. Authenticate

curl -X POST https://api.dimes.fi/v1/prediction-markets/tokens \
  -H "Authorization: Api-Key dm_live_skey_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "wallet_address": "0x1234...abcd" }'

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-04-16T11:00:00.000Z"
}

JWTs expire in 1 hour. Full details: Authentication.

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

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

ApiKeyAuth obtains and refreshes JWTs automatically. For client-side code with a JWT already in hand, use JwtAuth — see SDK Installation.

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 automatically use whatever QueryClientProvider is in your tree.

2. List markets

curl https://api.dimes.fi/v1/prediction-markets/markets

Each market includes leverage.min_bps, max_bps, and step_bps — clamp input to those. Full shape: API Reference — Markets.

import { useMarkets } from "@dimes-dot-fi/sdk/react";

function MarketList() {
  const { data, isLoading } = useMarkets();

  if (isLoading) return <div>Loading...</div>;

  return (
    <ul>
      {data?.data.map((market) => (
        <li key={market.ticker}>{market.title}</li>
      ))}
    </ul>
  );
}

3. Request a quote

curl -X POST https://api.dimes.fi/v1/prediction-markets/quotes \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "market_ticker": "will-btc-hit-100k-2026",
    "effective_side": "yes",
    "leverage_bps": 50000,
    "notional_amount_usd_pips": "250000000",
    "slippage_bps": 300
  }'

The response carries pricing, fees, liquidation parameters, and a contract_signature for the on-chain call. Full shape and signature verification: API Reference — Quotes.

Draft + promote: Quotes expire in 15 seconds. Call /draft-quotes first (no expiry), let the user review, then /promoted-quotes/{draft_quote_id} when they're ready. See API Reference — Promote draft quote.

import { executeQuote } from "@dimes-dot-fi/sdk";

const result = await executeQuote(client, {
  marketTicker: "will-btc-hit-100k-2026",
  side: "yes",
  collateralUsd: 25,
  leverageBps: 50000,
  slippageBps: 300,
});

console.log(result.quote.entryPriceUsd, result.quote.leverageBps);

executeQuote handles the draft → promote flow, retries on market-moved errors, and auto-corrects leverage/collateral/slippage when the API suggests adjustments.

Hook into each stage:

const result = await executeQuote(client, params, {
  onDraftReady: (draft) => console.log("Draft:", draft.id),
  onMarketMoved: (event) => console.log("Retrying...", event.retryCount),
  onCorrection: (adj) => console.log("Adjusted:", adj.field, adj.toLabel),
});

import { useQuote } from "@dimes-dot-fi/sdk/react";

function QuoteButton({ marketTicker }: { marketTicker: string }) {
  const { state, execute, reset } = useQuote();

  const handleQuote = async () => {
    await execute({
      marketTicker,
      side: "yes",
      collateralUsd: 25,
      leverageBps: 50000,
      slippageBps: 300,
    });
  };

  return (
    <div>
      <button onClick={handleQuote} disabled={state.phase === "promoting"}>
        {state.phase === "idle" ? "Get Quote" : state.phase}
      </button>
      {state.quote && <div>Entry: {state.quote.entryPriceUsd}</div>}
    </div>
  );
}

useQuote manages the full state machine: idle → loading-draft → draft-ready → promoting → promoted.

4. Open the position

Two on-chain calls: pUSD.approve(vault, total_user_amount) then vault.createPosition(...) with the quote parameters. After the tx confirms, Multiply acquires tokens, finalizes on-chain, and emits position.opened.

pending → open → closing → closed
           ↓
       liquidated

import { ethers } from "ethers";

const usdc = new ethers.Contract(USDC_ADDRESS, ["function approve(address,uint256)"], signer);
const approvalAmount = BigInt(quote.total_user_amount_usd_pips) * 100n;
await usdc.approve(quote.polygon_vault_contract_address, approvalAmount);

const VAULT_ABI = [
  "function createPosition(bytes16,bytes32,uint256,uint256,uint32,uint256,uint16,uint16,uint16,uint256,bytes,uint256) external",
];
const vault = new ethers.Contract(quote.polygon_vault_contract_address, VAULT_ABI, signer);

const tx = await vault.createPosition(
  quote.position_seed_hex,
  quote.polymarket_market_id,
  BigInt(quote.polymarket_token_id),
  BigInt(quote.collateral_usdc_units),
  quote.leverage_bps,
  BigInt(quote.notional_usdc_units),
  quote.origination_fee_bps,
  quote.lifetime_fee_apr_bps,
  quote.liquidation_fee_bps,
  BigInt(quote.expected_open_trading_fee_usdc_units),
  quote.contract_signature,
  BigInt(quote.signature_expiry),
);
await tx.wait();

Code examples for Polymarket Safe, Proxy, and Deposit Wallet patterns: On-Chain Integration.

import { buildCreatePositionTx, buildApproveTx, verifyQuoteSignature } from "@dimes-dot-fi/sdk/contract";

// Verify the quote signature against on-chain contract info
await verifyQuoteSignature(client, result.quote, userAddress);

// Build approve + createPosition transactions (viem-compatible)
const approveTx = buildApproveTx(usdcAddress, vaultAddress, approvalAmount);
const createTx = buildCreatePositionTx(result.quote);

// Submit with viem's walletClient
await walletClient.writeContract(approveTx);
await walletClient.writeContract(createTx);

buildCreatePositionTx returns a viem-compatible object (address, abi, functionName, args) — pass it directly to walletClient.writeContract().

5. Monitor positions

curl "https://api.dimes.fi/v1/prediction-markets/positions?status=open" \
  -H "Authorization: Bearer <jwt>"

Each position carries P&L, mark price, margin health, liquidation price, and accrued fees. Display rules: UI Guidelines.

import { usePositions } from "@dimes-dot-fi/sdk/react";

function OpenPositions() {
  const { data: positions, isLoading } = usePositions({ status: "open" });

  if (isLoading) return <div>Loading...</div>;

  return (
    <ul>
      {positions?.map((p) => (
        <li key={p.id}>
          {p.marketTicker} — {p.current.unrealizedPnlUsd}
        </li>
      ))}
    </ul>
  );
}

6. Close

The owner calls vault.requestClose(position_key). Multiply sells tokens, distributes proceeds, emits position.closed. If the market resolves first, settlement is automatic.

const VAULT_ABI = ["function requestClose(bytes32) external"];
const vault = new ethers.Contract(vaultAddress, VAULT_ABI, signer);

const tx = await vault.requestClose(position.on_chain_position_key);
await tx.wait();

Code: On-Chain Integration — Closing.

What's next

SDK Installation — setup, entry points, and peer dependencies
Sandbox — how to get a sandbox key and test pUSD
Environments — sandbox vs production
Contract Addresses — verify what you're approving against
Authentication — key management and rotation
On-Chain Integration — contract calls, wallet patterns, ABI
API Reference — full endpoint documentation
WebSocket Events — real-time position state changes
Error Handling — error codes and retry logic
UI Guidelines — leverage sliders and position cards

Need help? Telegram link at dimes.fi.

PreviousGetting Started NextSDK Installation

Last updated 17 days ago