Position Management

What are split, merge, and convert?

Polymarket positions are ERC-1155 tokens representing outcomes. Three on-chain operations let you manage them directly: Split — Turn collateral into YES + NO tokens for a market. Current V2 trading uses pUSD; explicit legacy V1 uses USDC.e. You put in

100 and get 100 YES shares + 100 NO shares. One side will be worth

1 at resolution, the other $0. Merge — The reverse. Put YES + NO tokens back together and receive the matching collateral. In current V2, 100 YES + 100 NO returns 100 pUSD. Convert — Rebalance positions across outcomes in a multi-outcome market (neg-risk only). The legacy neg-risk adapter converts selected NO tokens into USDC.e plus YES tokens on the remaining outcomes.

When to use each

Operation	Use case
Split	Mint new outcome tokens without going through the orderbook. Useful for market making or taking positions on illiquid markets.
Merge	Exit positions without selling on the orderbook. Merge paired YES+NO tokens back into the active collateral.
Convert	Rebalance across outcomes in multi-outcome markets (e.g. “Who will win the World Cup?”). Swap your NO exposure on some outcomes into YES exposure on others.

TypeScript (gasless)

The TypeScript SDK executes these operations gaslessly through the Polymarket relayer. No MATIC/POL needed.

npm install polynode-sdk@latest

Split

import { PolyNodeTrader } from 'polynode-sdk';

const trader = new PolyNodeTrader({ polynodeKey: 'pn_live_...' });
await trader.ensureReady('0xYOUR_PRIVATE_KEY');

// Split 100 pUSD into YES + NO tokens on current V2
const result = await trader.split({
  conditionId: '0x895e01db...', // from market data
  amount: 100,
});

console.log(result.txHash); // on-chain transaction hash

Merge

// Merge YES + NO tokens back into 50 pUSD on current V2
const result = await trader.merge({
  conditionId: '0x895e01db...',
  amount: 50,
});

Convert

Convert is only available on neg-risk multi-outcome markets (e.g. “Republican Presidential Nominee” with 36 outcomes).

// Convert NO positions on outcomes 0 and 1 ($100 each)
const result = await trader.convert({
  marketId: '0xc7d902c4...', // negRiskMarketID from market data
  outcomeIndices: [0, 1],     // which outcomes to convert
  amount: 100,                // $100 per outcome
});

What happens:

Your NO tokens on outcomes 0 and 1 are burned
You receive (number of outcomes - 1) x amount in USDC.e (here: $100)
You receive YES tokens on all other outcomes (here: outcomes 2 through 35)

The outcomeIndices correspond to the position of each outcome in the market. Index 0 is the first outcome, index 1 is the second, etc. You can find these by looking at the questionID field in market data — the last byte of each questionID is the outcome index.

Rust

The existing Rust helpers remain build-only for integrations that submit their own transactions:

use polynode::trading::position_management::*;

// Build a split transaction
let tx = build_split_txn(
    "0x895e01db...", // conditionId
    100.0,            // $100
    true,             // neg_risk
);

// tx.to = contract address
// tx.data = ABI-encoded calldata
// Submit via your provider or the Polymarket relayer

// Build a convert transaction
let tx = build_convert_txn(
    "0xc7d902c4...", // marketId
    &[0, 1],          // outcome indices
    100.0,             // $100 per outcome
);

For an EOA-controlled Safe or deposit wallet in user_owned mode, execute_split() and execute_merge() submit gaslessly with wallet-owned authorization:

use polynode::trading::{
    ExecutionMode, MergeParams, PolyNodeTrader, PrivateKeySigner,
    SignatureType, SplitParams, TraderConfig,
};

let signer = PrivateKeySigner::from_hex(
    &std::env::var("POLYGON_PRIVATE_KEY")?,
)?;
let mut trader = PolyNodeTrader::new(TraderConfig {
    polynode_key: std::env::var("POLYNODE_API_KEY")?,
    execution_mode: ExecutionMode::UserOwned,
    ..Default::default()
})?;

let ready = trader.ensure_ready(Box::new(signer), None).await?;
assert!(matches!(
    ready.signature_type,
    SignatureType::PolyGnosisSafe | SignatureType::Poly1271
));

trader.execute_split(SplitParams {
    condition_id: "0x895e01db...".into(),
    amount: 1.0,
}, false).await?;
trader.execute_merge(MergeParams {
    condition_id: "0x895e01db...".into(),
    amount: 1.0,
}, false).await?;

Python

The synchronous Python helpers also remain build-only:

from polynode.trading.position_management import build_split_txn, build_convert_txn

# Build a split transaction
tx = build_split_txn("0x895e01db...", 100.0, neg_risk=True)
# tx.to, tx.data, tx.value — submit via your provider

# Build a convert transaction
tx = build_convert_txn("0xc7d902c4...", [0, 1], 100.0)

For an EOA-controlled Safe or deposit wallet in user_owned mode, use the explicit async execution methods:

import os
from polynode.trading import (
    ExecutionMode,
    MergeParams,
    PolyNodeTrader,
    SignatureType,
    SplitParams,
    TraderConfig,
)

trader = PolyNodeTrader(TraderConfig(
    polynode_key=os.environ["POLYNODE_API_KEY"],
    execution_mode=ExecutionMode.USER_OWNED,
))
ready = await trader.ensure_ready(os.environ["POLYGON_PRIVATE_KEY"])
assert ready.signature_type in (
    SignatureType.POLY_GNOSIS_SAFE,
    SignatureType.POLY_1271,
)

await trader.execute_split(SplitParams(
    condition_id="0x895e01db...",
    amount=1,
    neg_risk=False,
))
await trader.execute_merge(MergeParams(
    condition_id="0x895e01db...",
    amount=1,
    neg_risk=False,
))

Finding market IDs

To use these operations, you need the right identifiers from market data:

Field	Where to find it	Used by
`conditionId`	Market data from `/v1/events/search` or Gamma API	`split()`, `merge()`
`negRiskMarketID`	Market data (only on neg-risk markets)	`convert()`
Outcome index	Last byte of each outcome’s `questionID`	`convert()` outcomeIndices

// Example: finding IDs for a market
import { PolyNode } from 'polynode-sdk';
const pn = new PolyNode({ apiKey: 'pn_live_...' });

const results = await pn.searchEvents('Republican nominee', { limit: 1 });
const market = results.events[0].markets[0];
console.log(market.conditionId);       // for split/merge
console.log(market.negRiskMarketID);   // for convert

Neg-risk vs standard markets

	Standard markets	Neg-risk markets
Outcomes	2 (binary YES/NO)	Many (e.g. 36 candidates)
Split/Merge	Via CTF contract	Via NegRiskAdapter
Convert	Not available	Available
Auto-detection	TypeScript SDK handles this	TypeScript SDK handles this

The TypeScript SDK auto-detects the market type and routes to the correct contract. Rust and Python default to neg-risk (most multi-outcome markets). Pass neg_risk=False for standard binary markets.

Rust and Python keep their synchronous build-only helpers for compatibility and also provide gasless user-owned execute_split / execute_merge methods. Convert remains gasless through TypeScript; Rust and Python expose a build-only convert transaction.

Getting Started

Guides

Position Management

What are split, merge, and convert?

When to use each

TypeScript (gasless)

Split

Merge

Convert

Rust

Python

Finding market IDs

Neg-risk vs standard markets

​What are split, merge, and convert?

​When to use each

​TypeScript (gasless)

​Split

​Merge

​Convert

​Rust

​Python

​Finding market IDs

​Neg-risk vs standard markets

What are split, merge, and convert?

When to use each

TypeScript (gasless)

Split

Merge

Convert

Rust

Python

Finding market IDs

Neg-risk vs standard markets