On-Chain Integration

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

This guide 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.

---

Position lifecycle

A position involves two user-initiated on-chain transactions. Everything else is handled by the Multiply backend.

User action                          Backend (automatic)
───────────                          ───────────────────
1. Approve USDC
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 a smart-contract wallet. Four patterns are supported:

Pattern	Description	msg.sender to vault
Direct EOA	Plain wallet (no contract wrapper)	The EOA itself
Polymarket Safe	Standard 1-of-1 Gnosis Safe provisioned by Polymarket for some users	The Safe contract
Polymarket Proxy	EIP-1167 minimal proxy provisioned by Polymarket for some users	The Proxy contract
Polymarket Deposit Wallet	ERC-1967 proxy deployed via Polymarket's deposit wallet factory (new users)	The deposit wallet contract

Polymarket provisions one of these contract wallets depending on how the user registered. Deposit wallets are the default for new API users. To determine which type a given address is, call eth_getCode — a Safe has ~250 bytes of bytecode, a Proxy has ~92 bytes, a deposit wallet has ~252 bytes, and an EOA has none. You can also try calling getOwners() on it — Safes respond, others revert.

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

---

Opening a position (Direct EOA)

1. Approve USDC

The vault pulls USDC 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)

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)

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 and refunds collateral + origination fee + venue fee. A position.reverted event is emitted.

---

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)

Only the position owner (the wallet that called createPosition) can call requestClose.

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.

---

Wallet integration patterns

Polymarket Safe

Encode the vault calldata normally, wrap it in a SafeTx, have the owner sign, submit execTransaction.

import {ethers} from "ethers";

const SAFE_ABI = [
  "function nonce() view returns (uint256)",
  "function getTransactionHash(address,uint256,bytes,uint8,uint256,uint256,uint256,address,address,uint256) view returns (bytes32)",
  "function execTransaction(address,uint256,bytes,uint8,uint256,uint256,uint256,address,address,bytes) returns (bool)",
];

const safe = new ethers.Contract(safeAddress, SAFE_ABI, provider);
const vault = new ethers.Contract(vaultAddress, VAULT_ABI, provider);

// Encode the vault call
const data = vault.interface.encodeFunctionData("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),
]);

// Build SafeTx and get the hash
const nonce = await safe.nonce();
const safeTxHash = await safe.getTransactionHash(
  vaultAddress, 0, data, 0, 0, 0, 0, ethers.ZeroAddress, ethers.ZeroAddress, nonce,
);

// Owner signs the hash
const signature = await ownerSigner.signMessage(ethers.getBytes(safeTxHash));

// Anyone can submit (owner, partner backend, or relayer)
const tx = await safe.connect(submitterSigner).execTransaction(
  vaultAddress, 0, data, 0, 0, 0, 0, ethers.ZeroAddress, ethers.ZeroAddress, signature,
);
await tx.wait();

USDC approval must be a separate SafeTx before createPosition, or batched via Safe's MultiSend.

Polymarket Proxy

The owner EOA calls factory.proxy() directly. USDC approval can be batched in the same call.

import {ethers} from "ethers";

const PROXY_FACTORY = "0xaB45c5A4B0c941a2F231C04C3f49182e1A254052";
const PROXY_FACTORY_ABI = [
  "function proxy(tuple(address to, uint256 typeCode, bytes data, uint256 value)[]) payable returns (bytes[])",
];

const factory = new ethers.Contract(PROXY_FACTORY, PROXY_FACTORY_ABI, ownerSigner);
const vault = new ethers.Contract(vaultAddress, VAULT_ABI, provider);
const usdc = new ethers.Contract(usdcAddress, ["function approve(address,uint256)"], provider);

const approveData = usdc.interface.encodeFunctionData("approve", [vaultAddress, approvalAmount]);
const createData = vault.interface.encodeFunctionData("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),
]);

// Batch approve + createPosition in one transaction
const tx = await factory.proxy([
  {to: usdcAddress, typeCode: 1, data: approveData, value: 0},
  {to: vaultAddress, typeCode: 1, data: createData, value: 0},
]);
await tx.wait();

The owner EOA must call factory.proxy() directly — the proxy does not support off-chain signatures. Polymarket's hosted relayer will not relay vault calls.

Polymarket Deposit Wallet

Deposit wallets are Polymarket's newest wallet type for API users. They work with our vault the same way as Safes and Proxies — the deposit wallet is msg.sender to the vault, and USDC + position payouts flow through it.

The owner signs an EIP-712 Batch containing the vault calldata, then submits it through the Polymarket relayer. USDC approval and createPosition can be batched in a single Batch.

import {ethers} from "ethers";

const vault = new ethers.Contract(vaultAddress, VAULT_ABI, provider);
const usdc = new ethers.Contract(usdcAddress, ["function approve(address,uint256)"], provider);
const depositWallet = new ethers.Contract(
  depositWalletAddress, ["function nonce() view returns (uint256)"], provider,
);

// Encode inner calls (same calldata as the EOA path)
const approveData = usdc.interface.encodeFunctionData("approve", [vaultAddress, approvalAmount]);
const createData = vault.interface.encodeFunctionData("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),
]);

// Build the Batch
const nonce = await depositWallet.nonce();
const batch = {
  wallet: depositWalletAddress,
  nonce: nonce,
  deadline: Math.floor(Date.now() / 1000) + 240,
  calls: [
    {target: usdcAddress, value: 0, data: approveData},
    {target: vaultAddress, value: 0, data: createData},
  ],
};

// Sign the Batch via EIP-712 (see Polymarket docs for full type definitions)
const signature = await ownerSigner.signTypedData(
  {name: "DepositWallet", version: "1", chainId: 137, verifyingContract: depositWalletAddress},
  {
    Batch: [
      {name: "wallet", type: "address"}, {name: "nonce", type: "uint256"},
      {name: "deadline", type: "uint256"}, {name: "calls", type: "Call[]"},
    ],
    Call: [
      {name: "target", type: "address"}, {name: "value", type: "uint256"},
      {name: "data", type: "bytes"},
    ],
  },
  batch,
);

// Submit via the Polymarket relayer (requires a relayer API key)
await fetch("https://relayer-v2.polymarket.com/submit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "RELAYER_API_KEY": relayerApiKey,
    "RELAYER_API_KEY_ADDRESS": relayerApiKeyAddress,
  },
  body: JSON.stringify({
    type: "WALLET", from: ownerAddress, to: depositWalletFactoryAddress,
    nonce: nonce.toString(), signature: signature,
    depositWalletParams: {
      depositWallet: depositWalletAddress,
      deadline: batch.deadline.toString(),
      calls: batch.calls,
    },
  }),
});

The requestClose call follows the same pattern — encode requestClose(positionKey) as the inner call. See Polymarket's deposit wallet docs for wallet deployment, relayer setup, and contract addresses.

---

Contract ABIs

Vault

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

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

Use this file 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 are summarized below for reference:

[
  "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.