Introduction

Levana Perps is a perpetual swaps platform for the Cosmos ecosystem. It focuses on providing well-fundedness guarantees. Every position has locked collateral from a liquidity pool for potential gains, and positions are automatically closed when there is insufficient collateral to cover future fees. As a result of this setup, there are two primary audiences for using the Levana Perps platform:

• Traders wishing to be exposed to an asset on either a long or short position. This can include:
  • Speculation
  • Hedging risks
  • Arbitrage opportunities
• Liquidity providers wishing to receive passive rewards on their liquidity with minimal exposure to price movements.

This tutorial will walk you through the major components of the Levana Perps API with worked examples in TypeScript. You can use any language to communicate with the Levana Perps smart contracts. We have chosen to demonstrate this with TypeScript because the CosmJs library is a well supported library. In addition to CosmJs, the Levana team also uses our own cosmos-rs library for interacting with our contracts.

We also provide a sample project in Typescript if you prefer to clone and tweak from there.

Overview of Concepts

To properly interact with Levana Perps, it's helpful to have an overall concept of the platform. We recommend reviewing our high-level overview and whitepaper documents for more details. (NOTE: not currently publicly available, we will update this document with links when ready.) But as a minimal crash course in the platform and its terminology:

• Factory Each deployment of Levana Perps has a single factory contract. This is your starting point for discovering information on each individual market.
• Market A single trading pair, with a name such as ATOM_USD, OSMO_USDC, or ETH_BTC. Each of these names is made up of two components: the base asset and the quote asset.
• Base asset The asset that we are speculating on the price movement of. For example, in ATOM_USD, we are speculating on changes of the price of ATOM.
• Quote asset The asset that we are pricing the base asset in.
• Collateral asset Levana Perps supports using either the base or quote asset as collateral. For example, in the markets above, ATOM, USDC, and BTC are used as the collateral assets, respectively. As a caller of the Levana Perps API, you will need to interact with the market contract by depositing the appropriate collateral asset during different API calls.
• Liquidity Liquidity providers can deposit liquidity into the system. This liquidity will be available to traders to lock into their positions. Liquidity providers can choose to deposit in exchange for LP tokens, or they can elect to time-lock their tokens for xLP tokens. Both tokens result in rewards from the system, but xLP tokens receive a higher return.
• Position A single position open by a trader. This will be a long or a short, and will have some deposit collateral, leverage, and maximum gains. As the price moves, the active collateral on the position will go up (if the price moves in your favor) or down (if the price moves against you).

There's much more to the platform, but we'll get into more details once we're writing code.

Additional information

The following links may be useful while interacting with Levana Perps:

• High level overview
• Whitepaper
• Messages API docs
• CosmJs API docs
• CosmJs tutorial
• Platform explainer slides

List of factory contracts

We'll learn more about the factory soon. For now, we'll provide the factory contract addresses in current use

MAINNET

TESTNET