Positions and outcome tokens

A position is the shares you hold of one outcome of a market. Shares are ERC-1155 tokens of a conditional tokens contract, and each outcome has its own token ID: the outcome's onChainId.

Collateral and sharesCopy Anchor Link

Markets settle in USDT on BNB Chain. USDT there has 18 decimals, and so do shares: an amount of 1000000000000000000 (10¹⁸) is 1 USDT or 1 share. The REST API returns share amounts in these units, for example amount in Get positions.

1 USDT always backs one Yes share and one No share. That one fact explains every operation below.

Most traders only trade and redeem. When you buy Yes and another trader buys No, the exchange can split your combined USDT into the two shares. When you sell Yes and another trader sells No, it can merge the two shares back into USDT and pay you both. You don't need to split or merge yourself to trade.

Splitting and merging shares in the product docs shows both operations in the web app.

PayoutsCopy Anchor Link

When a market resolves, each share pays out:

A 50/50 result happens when a question can't be decided either way. A negative-risk question can't resolve 50/50. It resolves Yes or No, and at most one question of its category resolves Yes.

For example, if you buy 100 Yes shares at 0.40, you pay 40 USDT. If Yes wins, you redeem them for 100 USDT, a profit of 60 USDT. If No wins, they pay nothing and you lose the 40 USDT.

Redeeming has no deadline. See Resolution for when it becomes possible.

Which contract holds your sharesCopy Anchor Link

Where your shares live depends on two market fields, isNegRisk and isYieldBearing. The Deployed contracts page lists each contract's address.

The SDKs pick the right contract for you. See Manage positions for the code.

Binary marketsCopy Anchor Link

You call the conditional tokens contract directly, with the market's conditionId:

• splitPosition(collateralToken, parentCollectionId, conditionId, partition, amount)
• mergePositions(collateralToken, parentCollectionId, conditionId, partition, amount)
• redeemPositions(collateralToken, parentCollectionId, conditionId, indexSets)

For a Predict market, collateralToken is USDT, parentCollectionId is 0x0, and partition and indexSets are [1, 2]: Yes and No.

Negative-risk marketsCopy Anchor Link

You call the negative-risk adapter, which handles the linked questions for you:

• splitPosition(conditionId, amount)
• mergePositions(conditionId, amount)
• redeemPositions(conditionId, amounts), where amounts is [yesAmount, noAmount]
• convertPositions(negRiskOnChainId, indexSet, amount), which only negative-risk markets have. negRiskOnChainId is the category's field of that name. See Negative-risk markets.

Yield-bearing marketsCopy Anchor Link

In a yield-bearing market (isYieldBearing: true), the USDT backing the shares is deposited into the Venus lending protocol while it is locked. Your shares work the same way as in any other market: each one still splits, merges and redeems 1:1 against USDT. Yields in the product docs explains how the yield is paid out.

Your positionsCopy Anchor Link

Get positions returns the positions of the wallet you are logged in with, and Get positions by address those of any wallet. Each position has: