Creating Your First Order

This guide will walk you through executing your first trades on Ferum!

Prerequisites

This guide assumes you have knowledge about Aptos and have the latest version of Aptos CLI installed.

The below tutorial works on the Aptos testnet.

Trading

Step 1: Setup

Create a new directory somewhere: mkdir ferum-tut

In this directory, run through the aptos init --profile ferum-tut command as follows:

➜  ferum-tut aptos init --profile ferum-tut
Configuring for profile ferum-tut
Choose network from [devnet, testnet, mainnet, local, custom | defaults to devnet]
testnet
Enter your private key as a hex literal (0x...) [Current: None | No input: Generate new key (or keep one if present)]

No key given, generating key...
Account 5faff093cafb20a213b83882fb6ba81b92bd49008000e44effe3b745c90c133e doesn't exist, creating it and funding it with 100000000 Octas
Account 5faff093cafb20a213b83882fb6ba81b92bd49008000e44effe3b745c90c133e funded successfully

---
Aptos CLI is now set up for account 5faff093cafb20a213b83882fb6ba81b92bd49008000e44effe3b745c90c133e as profile ferum-tut!  Run `aptos --help` for more information about commands
{
  "Result": "Success"
}

Note that the network above was set to testnet.

This command will setup your CLI with a freshly created account on testnet. You can view your account details (private key, etc) by running cat .aptos/config.yaml

For convenience, set the address of Ferum as an environment variable:

➜  export set FERUM=0x09c94d95f00a30b11aa18052c0276ff890d6ae754d5214cc85c714fa5b7c4133

Step 2: Create Test Coins for Trading

Now let's fund your account with APTF and USDF, test tokens deployed by Ferum that allows anyone to mint freely. First, we need to register the tokens with our account so we can receive it:

➜  aptos move run \
  --type-args $FERUM::test_coins::APTF \
  --function-id 0x1::managed_coin::register \
  --profile ferum-tut
  
➜  aptos move run \
  --type-args $FERUM::test_coins::USDF \
  --function-id 0x1::managed_coin::register \
  --profile ferum-tut

Now we can mint some fresh tokens (100 APTF and 100 USDF):

➜  aptos move run \
  --function-id $FERUM::test_coins::mint_aptf \
  --args u64:10000000000 \
  --profile ferum-tut
  
➜  aptos move run \
  --function-id $FERUM::test_coins::mint_usdf \
  --args u64:10000000000 \
  --profile ferum-tut

Both APTF and USDF coin have 8 decimal places.

Step 3: Open and Fund Market Account

Before interacting/trading on Ferum, you need to open a market account and fund it.

# Open market account.
➜  aptos move run \
  --function-id $FERUM::market::open_market_account_entry \
  --type-args $FERUM::test_coins::APTF $FERUM::test_coins::USDF \
  --profile ferum-tut

Now we can fund the account.

# Deposit to market account.
➜  aptos move run \
  --function-id $FERUM::market::deposit_to_market_account_entry \
  --type-args $FERUM::test_coins::APTF $FERUM::test_coins::USDF \
  --args u64:10000000000 u64:1000000000000 \
  --profile ferum-tut

All numeric decimal values are formatted as standard 10 decimal place FixedPoints. The above values would be for 1 APT and 100 USDF.

Step 4: Place a Limit Order

We can now trade! Let's create an order using the add_order_entry instruction

# Place an order on the market.
➜  aptos move run \
  --function-id $FERUM::market::add_order_entry \
  --type-args $FERUM::test_coins::APTF $FERUM::test_coins::USDF \
  --args u8:1 u8:1 u64:10000000000 u64:10000000000 u32:1 u64:0 \
  --profile ferum-tut

Each Ferum market is identified by the coin types being traded. So the type-args param is identified with the market associated with the order.

The add_order_entry instruction takes positional arguments: the side, a price, a quantity, and a client_order_id.

• side: a u8 value representing the order side. 1 means you want to place a buy order. 2 means you want to place a sell order. See OrderSide for more details.

• type: a u8 value representing the Behaviour of the order. 1 means you want to place a GTC order. See Order Behaviours for more details.

• price: a u64 value representing the limit price for the order. If it's a sell, this is the lowest price you are willing to receive. If the order is a buy, this is the highest price you are willing to pay. The price is a FixedPoint number with 10 decimal places, and 0 is used for a market order.

• quantity: a u64 value representing the limit quantity for the order. The quantity is a FixedPoint number with 10 decimal places.

• client_order_id: u32 of extra metadata that can be attached to an order. In this example, we just pass in 0.

So above we placed a BUY order for 1 APT with a limit price of 1 USDF.

Step 5: Crank

After every order, cranks are necesary to complete settlement. See Crank for more details.

# Crank market.
aptos move run \
  --function-id $FERUM::market::crank_entry \
  --type-args $FERUM::test_coins::APTF $FERUM::test_coins::USDF \
  --args u8:10 \
  --profile ferum-tut

We can use the Ferum indexing API to see our order.

curl https://api.ferum.xyz/orders?owner="<ACCOUNT>" | jq .

{
  "data": [
    {
      "counter": 0,
      "owner": "0xdcd166a8422c44369b232d1a27fa4bd57fa428fe59af01f5bfa345be65c43358",
      "instrument_type": "0x1::aptos_coin::AptosCoin",
      "quote_type": "0xc4a97809df332af8bb20ebe1c60f47b7121648c5896f29dc37b4d2e60944e20d::test_coins::USDF",
      "side": "buy",
      "original_qty": "1",
      "price": "1",
      "type": "limit",
      "status": "pending",
      "client_order_id": "",
      "cancel_agent": "none",
      "remaining_qty": "1"
    }
  ],
  "cursor": null
}

You've just submitted your first order using Ferum!