Welcome to the Polkamarkets V2 Documentation!

When a Liquidity Provider adds liquidity to an existing market, two things will happen:
• the Liquidity Provider will be assigned with a number of shares of the Liquidity Pool pro rata the Liquidity Pool share that the Liquidity Provider is funding.
• if the outcome prices are not equal, the Liquidity Provider will receive shares of all the outcomes, except for the least likely, i.e. the least expensive outcome, at the moment of the funding.
To better understand how this works, let's dive into some details.

# Logic

As explained in the Automated Market Maker (AMM) and Trading and Price Calculation sections, the number of shares in a market is determined by a constant function that forces there to be a balance between the number of shares in the Liquidity Pool and the number of shares in the Outcome Share Pools.
When a Liquidity Provider adds liquidity to a market, they in fact increase the number of shares in all pools in that market.
If the number of outcome shares is equal (i.e. if the outcome prices are equal), adding liquidity will not change the balance of the equation, and therefore the Liquidity Provider will only receive shares of the Liquidity Pool in return for adding liquidity to the market.
If, on the contrary, the number of shares in each pool is unbalanced (i.e. if the outcome prices are not equal), then adding liquidity would change the balance of the equation, which would cause a change in outcome prices.
To avoid that, the AMM gives the Liquidity Provider shares from the most likely outcome(s), but not from the least likely outcome(s) (i.e. the outcome(s) with the lowest price), in addition to shares from the Liquidity Pool.

# Examples

## Adding Liquidity to a binary outcome market

The following examples use a binary outcome market, i.e. a market with only two outcomes.
👉
Example 1: Adding liquidity to a market with equal outcome prices Alice has just created a market with $100 USDC in liquidity; no trades have happened in this market. The market status is as follows:  Liquidity Value$100 USDC Outcome A Shares 100 Outcome B Shares 100 Outcome A Price $0.5 USDC Outcome B Price$0.5 USDC
Alice currently holds 100 shares of the Liquidity Pool. Alice believes this market could attract lots of forecasters, and decides to make it more enticing for them to trade in it by increasing the liquidity.
So she adds $1000 USDC in liquidity, changing the market status to the following:  Liquidity Value$1100 USDC Outcome A Shares 1100 Outcome B Shares 1100 Outcome A Price $0.5 USDC Outcome B Price$0.5 USDC
Since the market is balanced, Alice is given 1 share of the Liquidity per USDC provided in Liquidity, and now holds 1100 shares of the Liquidity Pool.
👉
Example 2: Adding liquidity to a market with unequal outcome prices A few trades have now happened in Alice's market from Example 1, and its current status is as follows:
 Liquidity Value $1100 USDC Outcome A Shares 861.17 Outcome B Shares 1405.07 Outcome A Price$0.62 USDC Outcome B Price $0.38 USDC Bob sees that the market is attracting forecasters and believes that, were it more liquid, it could attract even more. Having reviewed the Strategies and Risks for liquidity providers, Bob thinks that the market can yield a sufficient volume to offset and reward his risk through fees. According to Bob's analysis, it appears that Outcome A, the most likely outcome, is currently underpriced. Were its value to increase, he'd also benefit from the fact that providing liquidity now would get him a part of his funding in shares of Outcome A, not just in liquidity shares. Bob goes ahead and adds an additional$1000 USDC in liquidity.
This move causes the market to have the following temporary status:
 Liquidity Value $1100 +$1000 = $2100 USDC Outcome A Shares 861.17 + 1000 = 1861.17 Outcome B Shares 1405.07 + 1000 = 2405.07 In the current state, the all-important constant formula is broken, as 2100^2 != 1861.17 * 2405.07. This would cause the outcome prices to change, so the smart contract calculates how many shares it should remove from the pools and give to Bob in order to maintain the constant, and not impact the outcome prices. Given that Outcome A is the most likely, it calculates how many shares of Outcome A the pool should keep, and how many it should attribute to Bob. The formula is: And the market is now rebalanced:  Outcome A Shares 1474.07 Outcome B Shares 2405.07 Liquidity Value Outcome A Price 0.62 Outcome B Price 0.38 In the end, Bob gets the following shares for adding$1000 USDC in liquidity to the market:
 Liquidity Shares 1882.88 - 1000 = 882.88 Outcome A Shares 1861.17 - 1474.07 = 387.10

## Adding Liquidity to a multiple outcome market

👉
Example 3: Continuing the multiple outcome example from Trading and Price Calculation, we have a market originally created by Charlie with the following characteristics:
 Pool Shares Price Liquidity 1000 N/A Outcome A 461.53 0.48 Outcome B 1294 0.17 Outcome C 1294 0.17 Outcome D 1294 0.17
Dylan, who already bought shares of Outcome A, believes that this market would benefit from more liquidity. He knows that if he adds liquidity now, he’ll only get shares from Outcome A along with Liquidity Pool shares, since Outcomes B, C and D are all priced equally. This makes it easier for him to manage his risk. Otherwise, he’d get shares from all Outcomes except for the one with the lowest price.
So Dylan decides to add 1000 \$USDC in Liquidity, which gives us the following temporary state:
 Pool Shares Liquidity 1000 + 1000 = 2000 Outcome A 461.53 + 1000 = 1461.53 Outcome B 1294 + 1000 = 2294 Outcome C 1294 + 1000 = 2294 Outcome D 1294 + 1000 = 2294
In the current state, the market is unbalanced. So the AMM will calculate how many shares Dylan should get for his contribution from the Liquidity Pool and from Outcome A, and rebalance the market so that the AMM constant remains true and outcome prices don’t change.
The formulas we’ll use are the same as the ones used for binary outcome markets.
There are three Outcomes that meet the condition for being the least likely, and the number of shares of these outcomes is 2294. Note that we don’t add the number of shares, we just use the number of shares related of one outcome.
Once we have the number of shares that remain in the pool, we can calculate the number of liquidity pool shares.
 Pool Shares Outcome A (rounded) Outcome B 2294 Outcome C 2294 Outcome D 2294 Liquidity (rounded)
And now we can calculate how many LP and Outcome A shares will be given to Dylan with a simple subtraction:
 Pool Shares Liquidity 1769.68 - 1000 = 769.68 Outcome A 1461.53 - 812.46 = 649.07
Now, for the sake of this example, let’s make sure that the outcome prices remain unchanged. For this, we’ll use the formulas learned in Trading and Price Calculation.
First, we calculate the Price Weight of all Outcomes using the formula:
 Outcome Outcome Price Weight Outcome A Outcome B Outcome C Outcome D
And now we can calculate the outcome prices using the following formula:
And so we get the following sum of all price weights:
Which we can use to calculate the price of each outcome:
 Outcome Outcome Price Outcome A (rounded) Outcome B (rounded) Outcome C (rounded) Outcome D (rounded)
These correspond to the initial outcome prices, so we know we did our calculation for adding liquidity correctly 💪

A special thank you to Polkamarkets Discord member NFT_Trader for helping write the example for adding liquidity in multiple outcome markets.