On-Chain Integration

How to submit on-chain transactions to open and close leveraged positions, and what the backend handles automatically after each step.

Covers the on-chain transactions your integration must submit. For quote parameters and field mappings, see the API Reference. For the full flow end-to-end, see the Quickstart.

Runnable examples: 03-open-position-onchain.ts (approve → verify signature → createPosition with viem) and 04-positions-and-close.ts (list positions, request close). Both are type-checked against the SDK in CI.

---

Position lifecycle

Two user-initiated on-chain transactions. Everything else is handled by the Multiply backend.

User action                          Backend (automatic)
───────────                          ───────────────────
1. Approve pUSD
2. Call createPosition() ──────────► Detect event
                                     Place exchange order
                                     Finalize on-chain
                                     ──► position.opened WebSocket event

3. Call requestClose() ────────────► Detect event
                                     Sell tokens on exchange
                                     Distribute proceeds on-chain
                                     ──► position.closed WebSocket event

Other exits (no user action needed):
  Market resolves ─────────────────► Settle all positions
  Price breaches threshold ────────► Liquidate position

See WebSocket Events for event payloads.

---

Wallet types

The vault doesn't care whether msg.sender is an EOA or smart-contract wallet:

• Direct EOA — covered below.

• Polymarket Safe, Polymarket Proxy, Polymarket Deposit Wallet — smart-contract wallets provisioned by Polymarket. Deposit wallets are the default for new API users and use a different opening flow. See Smart Wallet Integration.

Critical: The wallet_address you pass to POST /prediction-markets/quotes must be the address that will be msg.sender on-chain. For smart-contract wallets that's the contract address, not the owner EOA. The wrong address fails the on-chain signature check.

---

Opening a position (Direct EOA)

1. Approve pUSD

The vault pulls pUSD from the caller via transferFrom. Approve the vault to spend the required amount first.

ethers.js

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);

SDK (viem)

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

const approveTx = buildApproveTx(usdcAddress, vaultAddress, approvalAmount);
await walletClient.writeContract(approveTx);

2. Call createPosition

All parameters come directly from the quote response.

ethers.js

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();

SDK (viem)

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

// Verify the quote signature against the contract-info endpoint (cached per-client)
await verifyQuoteSignature(client, quote, userAddress);

const createTx = buildCreatePositionTx(quote);
await walletClient.writeContract(createTx);

3. What happens next (automatic)

1. Backend detects the PositionCreated event

2. Places an exchange order for prediction market tokens

3. Finalizes on-chain via finalizeOpen

4. Emits position.opened over WebSocket

If the exchange order fails, the backend reverts the position, refunds collateral + origination fee + venue fee, and emits position.reverted.

---

Closing a position

The position owner calls requestClose on the vault. The positionKey is the on_chain_position_key field from GET /positions.

ethers.js

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();

SDK (viem)

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

const closeTx = buildRequestCloseTx(vaultAddress, positionKey);
await walletClient.writeContract(closeTx);

Only the position owner (the wallet that called createPosition) can call requestClose. The example above is the Direct EOA path — for smart-contract wallets, wrap requestClose in the wallet's batch (Smart Wallet Integration).

After the transaction confirms, the backend sells tokens, distributes proceeds, and emits position.closed over WebSocket.

---

Other exit paths

No user action required for these — the backend handles them automatically.

• Settlement: When a market resolves, all positions are settled. Emits position.settled.

• Liquidation: When margin health approaches zero, the position is liquidated. Emits position.liquidated. The liquidation price is on every position object at risk.current_liquidation_price_usd.

---

Contract ABIs

Vault

The full canonical vault ABI — every external function, event, and custom error — is published in the official UI repo:

canonical-leveraged-prediction-vault-v1-abi.json

Use it directly so your client can decode revert reasons (e.g. InsufficientCapital, SignatureExpired, UserCapitalExceeded) into named errors instead of raw selectors. The two methods you'll typically call:

[
  "function createPosition(bytes16 positionSeed, bytes32 marketId, uint256 tokenId, uint256 collateralUsdcUnits, uint32 leverageBps, uint256 notionalUsdcUnits, uint16 originationFeeBps, uint16 lifetimeFeeAprBps, uint16 liquidationFeeBps, uint256 venueFeeUsdcUnits, bytes signature, uint256 signatureExpiry) external",
  "function requestClose(bytes32 positionKey) external"
]

The vault address is returned in every quote response as polygon_vault_contract_address, and from GET /prediction-markets/contract-info.