More docs

Content Out of Date

This content is not maintained and refers to an out-of-date version of Perpetual Protocol.

For the latest documentation, see https://docs.perp.com

What is Smart Maker

Smart Maker was developed in 2023 and rolled out progressively in Perp v2 markets. By the end of 2023 all markets had Smart Maker active.

Smart Maker extends the limit order system to allow traders to access better liquidity when liquidity for their trade is poor. This includes offchain components but all user-facing actions are handled onchain.

A typical order using Smart Maker looks like this:

Order size and price impact is evaluated by the UI. If the trade is within a set size and price impact is above a set amount, Smart Maker will activate.
The user must approve the Smart Maker contract before making the first trade, in the same way limit orders work. Approval only needs to be done one time.
The user then signs a transaction that will be executed by Smart Maker.
Smart Maker adds liquidity to the tick where the order will fill, in the quantity needed to fill the order.
Smart Maker sends the order to be executed via the limit order system.

Note: Smart Maker is not eligible for Pool Party liquidity mining rewards.

Manual contract approval

In rare instances, the UI may fail to prompt the user to approve the Smart Maker smart contract prior to the first use of the system. To manually approve, follow the instructions below.

Prompting users to perform approvals via Etherscan is a common scam. Proceed with caution, and never perform an approval if you aren't completely sure of what you are doing.

Double check the smart contract addresses by searching in the Perpetual Protocol Discord.
1. Smart Maker:0xfd7bB5F6844a43c5469c972640Eddfa99597a547
2. Limit Order: 0x93B9DaC2d57AaD1966859E8d1b5cCF5b95de9af4
Go to the Smart Maker contract on Etherscan: https://optimistic.etherscan.io/address/0xfd7bB5F6844a43c5469c972640Eddfa99597a547
Go to the Contract tab
Go to the Write as Proxy tab
Open the 1. approve (0x4342e966) section
Enter the following parameters
1. delegate (address): 0x93B9DaC2d57AaD1966859E8d1b5cCF5b95de9af4 (this is the limit order smart contract)
2. actions (uint8): 1 (1 tells the contract to allow the delegated address to open/close positions on your behalf)
Connect your wallet to Etherscan using the "🔴 Connect to Web3" button
Click Write and approve the transaction in your wallet
If there is a problem with gas estimation, please contact support or check recent transactions on Optimism for recent gas prices.

vAMM model

Key terms

AMM: Automated market maker, a type of exchange where trades are made against a pool of liquidity with prices set automatically based on the makeup of the pool.

Orderbook: A list of orders posted by traders that will be matched with other traders whose orders coincide.

Maker: A person who creates an order for traders to trade against, or provides liquidity for traders to trade against.

Taker: A person who trades against an order created by a maker, or against liquidity provided by makers.

Perpetual Protocol v2 uses Uniswap v3 for processing trades, so a basic understanding of how trading works on Uniswap is helpful. Here's a helpful video explainer and blog post.

Learn more about how Perpetual Protocol uses Uniswap v3: Perpetual + Uniswap

Trades on Perpetual Protocol are performed using an AMM with virtual tokens, hence the term vAMM. This makes trading a bit different from order book based exchanges (CLOB).

Guaranteed Liquidity

The key advantage of AMM-based exchanges is you can always place your trade right away, no matter the size.

However, the size of the trade will affect the price impact of the trade—that is, how much your trade will move the asset price. So it is key to take note of the estimated price impact of your trade before placing it.

Price Movement

On an AMM style exchange, price only moves when a trade is made. The percentage the price moves for each trade is called price impact. The price impact is determined by the size of the trade and the available liquidity.

Small trade size + large liquidity available = small price impact
Big trade size + small liquidity available = large price impact

Price on the AMM does not follow spot prices on its own, and requires arbitrageurs to make trades, keeping the AMM price close to spot.

Price Ranges

Perpetual Protocol benefits from concentrated liquidity resulting from range pricing on Uniswap v3. This means that liquidity is placed in price ranges set by liquidity providers, called makers.

Your trade will always use liquidity from the current price range. If your trade is very large and exhausts liquidity in the current price range, you will cause the price to cross into other ranges.

Funding Tools

There are four ways to track funding payments for your positions on Perpetual Protocol:

Within the Perp UI using the funding rate chart,
The R72.FI website offered by the community,
Through The Graph,
The Perpetual Protocol v2 trader dashboard on Dune Analytics, created by Perpvangelist Shogun.

Let's take a look at each in turn.

Perp UI

The funding chart is shown within the UI, next to 'Price' on the trading chart. Click on 'Funding Rate' to show the time series chart of the funding rate.

Several options are available for displaying the funding rate: the 1 hour funding rate, 8-hour funding rate and annualized. You can also specify a custom date range and download the data as a CSV file.

R72.FI

Community maintained tool. May be out of date.

Go to https://www.r72.fi/derivative/perpetual_protocol to see the historical funding rates for the markets on Perp.

Click on a particular trading pair (e.g., ETH:USD) to see a time series chart of the funding rate. You can change the time period using the dropdown menu on the top right-hand side:

The Graph

The Graph provides data via GraphQL that can be used for further processing locally.

Link to subgraph Funding example: https://thegraph.com/hosted-service/subgraph/perpetual-protocol/perpetual-v2-optimism?query=List%20FundingUpdateds

Click on the play button to retrieve the daily funding rate across all markets on Perp.

The 24-hour funding rate shown here based on a 15-minute time-weighted average price that is updated with each Ethereum L1 block.

The fundingRatePerBlock can be calculated as:

latest dailyFundingRate * blockPeriod / 86400

where latest dailyFundingRate can be fetched from The Graph (as shown above) and the block period = (current block timestamp - previous block timestamp).

Perpetual Protocol v2 Trader Dashboard

Navigate to the Dune dashboard, enter your address in the wallet address field, select a time period and then click on the "Apply all parameters"

Then scroll down to the bottom of the dashboard to see your past funding payments (using the Perp funding payments trader chart) and pending funding payments (under the pending funding chart):

How to Trade Directly with the Smart Contracts

As you may have seen with recent events, user interfaces are susceptible to hacks and are not yet decentralized enough. One way to avoid interacting with fraudulent UIs is to bookmark all of the contract addresses you frequently interact with. If the front end has been exploited, then as you go to interact with it, a different address that’s not in your bookmarks will be displayed, raising the alarm that something’s not right and preventing you from incurring losses.

Another method to avoid being deceived by a fraudulent front end is to trade directly with the smart contracts via Etherscan. In this guide, we’ll show you how to trade directly with the Perpetual Protocol smart contracts, so you can still open or close trades in the extreme event that our UI is compromised.

To deposit, withdraw and open or close positions on Perp v2, there are two smart contracts you’ll need to interact with:

the Vault contract, for deposits and withdrawals: 0xad7b4c162707e0b2b5f6fddbd3f8538a5fba0d60
And the Clearinghouse contract, for executing trades: 0x82ac2ce43e33683c58be4cdc40975e73aa50f459

Let’s see how you can interact directly with the smart contract using Etherscan to make trades.

How to Deposit

To get started, you’ll have to make a deposit to the vault contract address.

Head over to the following page on optimistic.etherscan: https://optimistic.etherscan.io/address/0xad7b4c162707e0b2b5f6fddbd3f8538a5fba0d60#writeProxyContract

Click on “Connect to Web3” to connect to the site.

Select wallet type (MetaMask or WalletConnect):

Once connected, the red circle will turn green:

Click “1. Deposit”, then enter the token address of the collateral you want to deposit (USDC, ETH, WETH or FRAX) and the deposit amount.

USDC token address: 0x7F5c764cBc14f9669B88837ca1490cCa17c31607
ETH token address: 0xDeadDeAddeAddEAddeadDEaDDEAdDeaDDeAD0000
WETH token address: 0x4200000000000000000000000000000000000006
FRAX token address: 0x2E3D870790dC77A83DD1d18184Acc7439A53f475

Example: Deposit $100 USDC

If you want to deposit $100 worth of USDC, then you’d input 100 * 10^18 = 100000000000000000000 into the amount field and enter 0x7F5c764cBc14f9669B88837ca1490cCa17c31607 in the token address field, as shown below:

[“0x7F5c764cBc14f9669B88837ca1490cCa17c3160”]

[100000000000000000000]

Click on “Write” and confirm the transaction in your wallet.

Example: Deposit 0.10 ETH

If you want to deposit 0.10 ETH, then you’d input 0.1 * 10^18 = 100000000000000000 into the amount field and enter 0xDeadDeAddeAddEAddeadDEaDDEAdDeaDDeAD0000 in the token address field instead.

How to Open a Position

To open a position, you’ll need to interact with the Clearinghouse contract, which can be done here: https://optimistic.etherscan.io/address/0x82ac2ce43e33683c58be4cdc40975e73aa50f459#writeProxyContract

To open a position, head down to “8. openPosition'' and click on the arrow to reveal the field.

As covered in our Integration Guide and Code Samples, you have to input various parameters to open a position, each of which are explained below.

struct OpenPositionParams { 
address baseToken; 
bool isBaseToQuote; 
bool isExactInput; 
uint256 amount; 
uint256 oppositeAmountBound; 
uint256 deadline; 
uint160 sqrtPriceLimitX96; 
bytes32 referralCode; }

address baseToken can be found for each market by following the links listed in the liquidity pool info help center article.

Once you’re on the pool information page, you can then click on the base token (highlighted below) to get the relevant v-token address. For example, if you want to trade vAAVE (the base token of the AAVE-USD market), then the base token address is: 0x34235c8489b06482a99bb7fcab6d7c467b92d248.

The isBaseToQuote parameter is used to specify if you want to go long or short the asset for the v-token pool address you have specified.
- To short the base asset, enter ‘true’
- To long the base asset, enter ‘false’
- isExactInput can be entered as true or false.
- The uint256 amount parameter specifies the size of your position. For example, if you want to trade $50 worth of AAVE, then you should input 50 * 10^18 // 18 decimals = 50000000000000000000.

uint160 sqrtPriceLimitX96 is a restriction on the ending price after the swap, where sqrtPriceLimitX96 is defined here. For no restriction, you can enter 0.
referralCode is used to add your referral code (or use 0x0000000000000000000000000000000000000000000000000000000000000000 if you do not have a code to apply).

Putting it all together, here’s an input for shorting $50 worth of AAVE:

["0x34235c8489b06482a99bb7fcab6d7c467b92d248",true,false,"50000000000000000000","0","1660666527","0","0x0000000000000000000000000000000000000000000000000000000000000000"]

To open the position, click on the “Write” button and confirm the transaction in your wallet.

Congratulations, you have now opened a position by interacting directly with the smart contract!

How to Close a Position

Closing a position is similar to opening one.

Go to “4. closePosition”:

Specify the address baseToken, sqrtPriceLimitX96, oppositeAmountBound, deadline, and referral code.

So for closing the $50 short position in the AAVE market, input the following:

["0x34235c8489b06482a99bb7fcab6d7c467b92d248",”0”,"0",”1660678522”,"0x0000000000000000000000000000000000000000000000000000000000000000"]

Then click “Write” and confirm the transaction in your wallet.

How to Withdraw

To withdraw funds, head to “16. Withdraw” from the vault contract.

Similar to depositing, you just specify the token address of the asset you want to withdraw and the amount.

Example: Withdraw $100 USDC

If you want to withdraw $100 worth of USDC, then you’d input 100 * 10^18 = 100000000000000000000 into the amount field and enter 0x7F5c764cBc14f9669B88837ca1490cCa17c31607 in the token address field, as shown below:

[“0x7F5c764cBc14f9669B88837ca1490cCa17c3160”]

[100000000000000000000]

Click on “Write” and confirm the transaction in your wallet.

Example: Withdraw 0.10 ETH

If you want to withdraw 0.10 ETH, then you’d input 0.1 * 10^18 = 100000000000000000 into the amount field and enter 0xDeadDeAddeAddEAddeadDEaDDEAdDeaDDeAD0000 in the token address field instead.