Simple Trading Session

This guide will walk you through a simple trading session. It will be assumed that a flow trading server is running locally (refer to the Quick Start guide if necessary) and that curl, date, and jq commands are available in your system path.

By the end of this guide, you will have learned to generate and submit bids and gained a basic understanding of working with a flow-trading based marketplace.

Setup

The demonstration flow trading server assumes that valid bidders possess a cryptographically-signed token attesting their identity, known as a JSON Web Token. This allows the flow trading server to defer the complexity of user management and authenticaton to external systems controlled by the market operator.

Caution

For the purposes of this guide, the background flow trading server will be assumed to have launched with ---api-secret SECRET. The examples below will not work if the secret is any other value.

Accordingly, we will need to generate these tokens for our trading session. Copy and paste the below variables into your bash or zsh session:

# Change this to the location of your server, if different
API_SERVER=http://localhost:8080
# Signed JWT for user 11111111-1111-8111-8111-111111111111
JWTB1=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMTExMTExMS0xMTExLTgxMTEtODExMS0xMTExMTExMTExMTEifQ.jIy_I8E-VW1ToODyVzqU6dLrLaXKnbFGDvbqTs4N-Jo
# Signed JWT for user 22222222-2222-8222-8222-222222222222
JWTB2=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIyMjIyMjIyMi0yMjIyLTgyMjItODIyMi0yMjIyMjIyMjIyMjIifQ.4x0mSmuS9s9CnMOYhjTd8WPB2ZUo0P3V0ak5Mdc0W1c
# Signed JWT for an admin user
JWTADMIN=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJGRkZGRkZGRi1GRkZGLUZGRkYtRkZGRi1GRkZGRkZGRkZGRkYiLCJhZG1pbiI6dHJ1ZX0.CV3aldMRLqaRY2UsKYxFpC-tWI8EbJoXl7YlF4gYcjY

Note

Notice that bidder ids are simply UUIDs. In fact, the decoded JWT tokens above correspond to { sub: <BIDDER_ID> }. (The admin token also includes a custom claim admin: true.)

Product Definition

Before engaging in trading, the market must define products to be traded. Using our admin token, we can define a list of products and get back their server-generated IDs for later use. Copy and paste the below to create a single product and store its ID in the environment variable PRODUCT.

PRODUCT=$(\
  curl -s -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $JWTADMIN" \
    --data '[{ "kind": "DEMO", "from": "2030-01-01T00:00:00Z", "thru": "2030-01-01T06:00:00Z" }]' \
    $API_SERVER/admin/products \
  | jq -r '.[0]' \
)

The demonstration server defines products via a triplet (kind, from, thru), which is suitable for trading in a forward market where products are primarily characterized by their delivery window, alongside a categorical label of “what” it is. One can imagine defining products for every hour of every day of every year, with kind’s reflecting a location (kind = NORTH_AMERICA), a type (kind = OPTION), or both (kind = NORTH_AMERICA/OPTION).

Tip

The reference flow trading implementation is easily customized for different product definitions. For the example above where kind is both a location and a type joined together, it may be beneficial to fork the implementation and swap in a definition that explicitly separates the two, rather than relying on a convention of string concatenation.

Submissions

A bidder has at most one submission, which is comprised of auths and costs. We will keep things simple and define a single auth that trades the single product without restriction. We will also assign a cost to this auth that expresses the piecewise-linear, non-increasing demand for the underlying products. The server takes the unifying convention of positive demand corresponding to buying and negative demand to selling.

curl -s -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer $JWTB1" \
  --data '{
    "auths": [{
      "auth_id": "11111111-AAAA-8111-8111-111111111111",
      "portfolio": { "'"$PRODUCT"'": 1 },
      "data": {}
    }],
    "costs": [{
      "cost_id": "11111111-CCCC-8111-8111-111111111111",
      "group": { "11111111-AAAA-8111-8111-111111111111": 1 },
      "data": [{ "rate": 0, "price": 15 }, { "rate": 20, "price": 5 }]
    }]
  }' $API_SERVER/v0/submissions/11111111-1111-8111-8111-111111111111 | jq .

The server will echo the submission back if was successfully parsed and accepted.

We also define a submission for the other bidder, selling the same product:

curl -s -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer $JWTB2" \
   --data '{
    "auths": [{
      "auth_id": "22222222-AAAA-8222-8222-222222222222",
      "portfolio": { "'"$PRODUCT"'": 1 },
      "data": {}
    }],
    "costs": [{
        "cost_id": "22222222-CCCC-8222-8222-222222222222",
        "group": { "22222222-AAAA-8222-8222-222222222222": 1 },
        "data": { "max_rate": 0, "price": 10 }
    }]
  }' $API_SERVER/v0/submissions/22222222-2222-8222-8222-222222222222 | jq .

Here we used an alternate specification of the cost, restricting the trade to nonpositive rates.

Note

The respective pages on auths and costs provide details on how they relate to specific outcomes a bidder might seek to achieve. Their full definition ties deeply into the underlying mathematics of flow trading so this discussion is best saved for later.

Tip

The /v0/submissions/{bidder_id} endpoint is actually an atomic wrapper around the individual /v0/auths/{auth_id} and /v0/costs/{cost_id} endpoints. It is simpler for the purposes of this guide to utilize this bulk endpoint, but sometimes a bidder may prefer to edit their submission’s constituent primitives directly.

Auctions

Auctions are explicitly triggered by an administrator. This allows the logic of both when and how often to run an auction to be externalized elsewhere in the market operator’s systems.

Auctions consist of

1. Taking all bidders’ submissions as-of a point in time,
2. Defining a duration (e.g. “now” to “now + 1 hour”),
3. Solving a mathematical optimization program and reporting the results.

The following command will run a single auction spanning the next hour:

curl -s -i -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $JWTADMIN" \
  --data '{ "by": "1h", "thru": "'"$(date --date="+1 hour" -Iseconds 2>/dev/null || date -v+1H -Iseconds 2>/dev/null)"'" }' \
  $API_SERVER/admin/auctions/solve

Running an auction may take a few moments, so unlike the other endpoints we have interacted with, this endpoint will not return the auction results. Instead, it should have responded with an HTTP/1.1 202 Accepted message, which says the solve request was accepted and scheduled for processing.

To see the outcomes of these auctions once they are available, there are results endpoints available querying:

# Bidder 1's outcomes for each auction
curl -s -H "Authorization: Bearer $JWTB1" $API_SERVER/v0/auths/11111111-AAAA-8111-8111-111111111111/outcomes | jq .

# Bidder 2's outcomes for each auction
curl -s -H "Authorization: Bearer $JWTB2" $API_SERVER/v0/auths/22222222-AAAA-8222-8222-222222222222/outcomes | jq .

# The demonstration product's outcomes for each auction
curl -s $API_SERVER/v0/products/$PRODUCT/outcomes | jq .

Next Steps

For building a client, the OpenAPI schema (available at http://localhost:8080/rapidoc or wherever the server is running) lists all the available server endpoints. The documentation available at https://docs.rs/fts-core/latest/fts_core is also a good starting point to learn more about the various operations the server implements.

For learning more about flow trading, it is recommended to read the guides on auths and costs.