You are viewing an archive of the Piccadilly Circus Games Competition. Join our Discord for the latest information.

Use the CAX

Recipes for how to interact with the Centralized Auton Exchange (CAX). Create an account on CAX with your participant key and transact on the exchange in the round’s On-chain Tasks!

Synopsis

This page details:

  • resources for how to get set up and interact with the off-chain exchange CAX
  • how to get an API Key to access your CAX account (using your participant account private key to create an API Signature)
  • how to deposit your mock USDC to CAX for trading in ATN and NTN
  • how to submit a trade to purchase a protocol asset (i.e. ATN or NTN)

Get setup to access your CAX account

Your account on CAX is automatically created when you register for the Games. It is associated with your registered participant account so you can move assets between on- and off-chain easily.

The exchange uses API Keys for authentication so you need to create an API key for your account before calling authenticated endpoints.

The API Key is then simply included as an HTTP Header to your HTTP request.

Rate limiting on CAX API calls

API requests exceeding 5 requests per second are rate limited up to a maximum of 20 requests per second.

Create your API Key

To create an API key, make a POST request to the /apikeys endpoint providing a signed message, which must be a UTF-8 encoded string representation of a JSON object containing a nonce key and a unique value. Creating the signature is easy, just use the aut tool you setup in the quick start.

When you submit the request include an API-Sig header that represents the signature of the message using the account’s private key. The request body must consist of the exact UTF-8 message text that was signed.

The response will provide the apikey value. This should be included as the API-Key header value in subsequent authenticated requests.

Just call the same endpoint with a new nonce value. A new API key is generated, which will replace the existing key.

  1. Create the message to sign as an environment variable. For example, use the current timestamp as a nonce:

    MESSAGE=$(jq -nc --arg nonce "$(date +%s%N)" '$ARGS.named')

    Printing this env variable should produce something like this:

    MESSAGE={"nonce":"1698772244N"}

  2. Sign the message with aut and write signature to a file. Configure aut to use your participant account key and run the sign-message command to create the signature. Pass in the value created in Step 1. and write output to a file:

    aut account sign-message $MESSAGE message.sig

  3. POST using HTTPie CLI to receive the new API key. Call the /apikeys endpoint passing in the signed message as the api-sig value:

    echo -n $MESSAGE | https https://cax.piccadilly.autonity.org/api/apikeys api-sig:@message.sig

    Your participant account address and your API key are returned as a JSON object. For example:

    {
 "account": "0xF6e02381184E13Cbe0222eEDe0D12B61E2DF8bE5",
 "apikey": "o7JESIcMBgH7sfc7piRkZuqT7HgCW7hPiU3GpbaiSVoqBcYqGByQ7LvIqm0GNI/DLvdfAkWxKLUdpc/VfpcyuRw="
}

Verify access - check your balance

To verify access, check your CAX account balances. This will return your mock USDC balance and ATN and NTN balances (which are zero).

  1. Call the CAX API /balances endpoint, where <APIKEY> is the apikey generated in step 3 above:

    https GET https://cax.piccadilly.autonity.org/api/balances API-Key:<APIKEY>

    Your exchange balances are returned:

    [
    {
        "available": "0.000000000000000000",
        "balance": "0.000000000000000000",
        "symbol": "ATN"
    },
    {
        "available": "0.000000000000000000",
        "balance": "0.000000000000000000",
        "symbol": "NTN"
    },
    {
        "available": "1000000.00",
        "balance": "0.00",
        "symbol": "USDC"
    }
]

Fund your account on CAX with mock USDC to trade

Once you have bridged your mock USDC to your participant account on Piccadilly, you need to deposit it to your CAX account to fund trading in the exchange’s ATN-USDC and NTN-USDC markets off-chain.

For how to do this, see the guide deposit mock USDC to off-chain on this page.

You are ready to trade!

Purchase ATN and NTN

To fund your participant account with ATN and NTN, submit a limit order to buy these using your mock USDC funding.

  1. Get the CAX orderbooks. Call the CAX API /orderbooks endpoint:

    https GET https://cax.piccadilly.autonity.org/api/orderbooks API-Key:<APIKEY>

    This will return ATN and NTN orderbooks, providing you with:

    • trading pairs and base and quote currencies
    • minimum amount of an order
    • tick size, i.e. the minimum amount the pair price can move by in the exchange

    You will see orderbook information for ATN and NTN:

    [
 {
     "base": "ATN",
     "min_amount": "0.01",
     "pair": "ATN-USDC",
     "quote": "USDC",
     "tick_size": "0.01"
 },
 {
     "base": "NTN",
     "min_amount": "0.01",
     "pair": "NTN-USDC",
     "quote": "USDC",
     "tick_size": "0.01"
 }
]

  2. Get the current quote price. Call the CAX API /quote endpoint where {pair} is ATN-USDC or NTN-USDC:

    https GET https://cax.piccadilly.autonity.org/api/orderbooks/{pair}/quote API-Key:<APIKEY>

    This will return ATN and NTN orderbooks, providing you with:

    • for buy and sell side, ask and bid price and amounts available
    • timestamp of the quote

    Prices and amounts depend on the market of course, but you could see something like this for ATN-USDC:

    {
 "ask_amount": "16.74",
 "ask_price": "1.00",
 "bid_amount": "1.50",
 "bid_price": "1.00",
 "timestamp": "2023-11-02T11:28:00.840248+00:00"
}

    And something like this for NTN-USDC:

    {
 "ask_amount": "2.56",
 "ask_price": "10.45",
 "bid_amount": "11.92",
 "bid_price": "10.27",
 "timestamp": "2023-11-02T11:35:04.964810+00:00"
}

  3. Trade ATN and NTN. Submit a limit order to make your trades, calling the CAX API /orders endpoint. Specify:

    • pair: orderbook pair, ATN-USDC or NTN-USDC
    • side: bid or ask depending on the direction of your trade
    • price: your trade price to 2 decimal places
    • amount: how much ATN or NTN you are trading to 2 decimal places
    https POST https://cax.piccadilly.autonity.org/api/orders API-Key:$KEY pair=<VALUE> side=<VALUE> price=<VALUE>  amount=<VALUE>

    For example, an order to purchase ATN for the quote price returned in Step 2 above could look like:

    https POST https://cax.piccadilly.autonity.org/api/orders API-Key:$KEY pair=ATN-USDC side=bid price=1.00  amount=10

    This will return order details, including order ID and the status, which will be pending:

    {
 "amount": "10.00",
 "order_id": 70,
 "pair": "ATN-USDC",
 "price": "1.00",
 "remain": "10.00",
 "side": "bid",
 "status": "pending",
 "timestamp": "2023-11-02T11:48:50.811765+00:00",
 "type": "limit"
}

  4. Verify order completed. Get order information to verify your trade is closed, calling the CAX API /orders/{order_id} endpoint. Pass in the order ID returned in Step 3 (70 in this example):

    https GET https://cax.piccadilly.autonity.org/api/orders/70 API-Key:$KEY

    This will return order info, including status, which will show closed when done. For the order example in Step 3 above it returns:

    {
    "amount": "10.00",
    "order_id": 70,
    "pair": "ATN-USDC",
    "price": "1.00",
    "remain": "0.00",
    "side": "bid",
    "status": "closed",
    "timestamp": "2023-11-02T11:48:50.811765",
    "type": "limit"
}

    That’s it!

You can do this by calling the CAX /trades endpoint.

See CAX API docs Get withdraws.

Transfer ATN, NTN, mock USDC on- and off- chain

To transfer Auton and Newton simply deposit and withdraw to the CAX:

  • deposit from your on-chain participant account by sending to the CAX exchange address
  • withdraw from your off-chain account to send to your participant account address

The exchange credits/debits your CAX account balances immediately.

You can do this:

  • off-chain by calling the CAX /balances endpoint. See CAX API docs Get balances and Get balance for symbol.
  • on-chain by using aut. Use the aut account balance command for ATN and the aut account balance --ntn command for NTN.

Withdraw from off-chain

To transfer funds on-chain to your participant account address call the CAX API /withdraws endpoint.

Withdrawal amounts and costs?

The minimum withdrawal amount in CAX is 1 ATN or 1 NTN.

There is no charge for withdrawing from CAX to your on-chain account.

Specify:

  • symbol: of the asset. One of ATN, NTN, or mock USDC
  • amount: how much of the asset you are transferring, to 2 decimal places
https POST https://cax.piccadilly.autonity.org/api/withdraws API-Key:$KEY symbol=<VALUE>  amount=<VALUE>

For example, to withdraw 10 ATN:

https POST https://cax.piccadilly.autonity.org/api/withdraws API-Key:$KEY symbol=ATN  amount=10

This will return transfer details:

{
    "amount": "10.000000000000000000",
    "status": "accepted",
    "symbol": "ATN",
    "timestamp": "2023-11-02T17:12:33.436809+00:00",
    "txhash": null,
    "txid": 8
}

CAX will transfer the funds to your participant account on-chain.

To check the status of your withdraw, you can query the /withdraws/<TXID> endpoint, here for example with 8 as the <TXID>:

https GET https://cax.piccadilly.autonity.org/api/withdraws/8 API-Key:$KEY

This will return the current status of your withdraw with txid 8:

{
    "amount": "10.000000000000000000",
    "status": "completed",
    "symbol": "ATN",
    "timestamp": "2023-11-02T17:12:33.436809+00:00",
    "txhash": "0xc871bf5eb5e3f37ea01619ec4193fd7fb65a8ec3a59c1bf0577b159515ec65dd",
    "txid": 8
}

You can do this by calling the CAX /withdraws endpoint.

See CAX API docs Get withdraws.

If your withdraw request has status error or failed, then you may be entitled to a refund.

Open a support ticket in Autonity Discord channel #user-support to request an investigation.

Funds lost by a failed withdrawal from off- to on-chain will be refunded to your CAX account.

You can see the history of refunds to your account by calling the CAX /refunds endpoint.

See CAX API docs Get refunds.

Deposit ATN or NTN to off-chain

To transfer funds from on- to off-chain, deposit to the exchange by sending to the CAX exchange address from your participant account address. Transfer using aut tx, specifying:

  • <RECIPIENT_ADDRESS>: the CAX Exchange address, given on this page in the Exchange resource links section
  • --value flag: amount to transfer
  • --ntn flag: if transferring NTN. Without the flag ATN is transferred
aut tx make --to <RECIPIENT_ADDRESS> --value <AMOUNT> --ntn | aut tx sign - | aut tx send -

You can do this by calling the CAX /deposits endpoint.

See CAX API docs Get deposits.

Deposit mock USDC to off-chain

To transfer mock USDC funds from on- to off-chain, deposit to the exchange by sending to the CAX exchange address from your participant account address. Mock USDC is an ERC 20 token contract so transfer using aut token transfer. Specify:

  • --token flag: the contract address of the mock USDC ERC20 token proxy contract on Piccadilly, given on this page in the Exchange resource links section
  • <RECIPIENT_ADDRESS>: the CAX Exchange address, given on this page in the Exchange resource links section
  • AMOUNT: amount to transfer
aut token transfer --token <TOKEN_ADDRESS> <RECIPIENT_ADDRESS> <AMOUNT> | aut tx sign - | aut tx send -

Retrieve trading data

Fetch historical trading data

You can obtain historical trading data for further analysis directly from the CAX. This is available at the /orderbooks/<PAIR>/trades endpoint for every order book. Check the Get trade history documentation for reference.

The endpoint returns 24 hours of trading data at a time. To obtain trading data for a previous day, pass the date as query parameter date with format YYYY-MM-DD. For example, to query trading data for the 11th March, run:

https GET https://cax.piccadilly.autonity.org/api/orderbooks/NTN-USDC/trades date==2024-03-11

This will return an array of trade data:

[
  {
    "timestamp": "2024-03-11T00:00:02.321875",
    "price": "10.96",
    "amount": "192592.59"
  },
  {
    "timestamp": "2024-03-11T00:00:03.204852",
    "price": "10.96",
    "amount": "462.97"
  },
  {
    "timestamp": "2024-03-11T00:00:19.572395",
    "price": "10.97",
    "amount": "218518.52"
  },
  ...
]

To obtain 24 hours of trading data ending now, just omit the date query parameter:

https GET https://cax.piccadilly.autonity.org/api/orderbooks/NTN-USDC/trades

This will return an array of trade data starting 24 hours ago and ending at the current time:

[
  {
    "timestamp": "2024-03-11T19:51:22.546196",
    "price": "10.81",
    "amount": "1000.00"
  },
  {
    "timestamp": "2024-03-11T19:59:26.446290",
    "price": "10.80",
    "amount": "10000.00"
  },
  {
    "timestamp": "2024-03-11T19:59:30.989938",
    "price": "10.80",
    "amount": "10000.00"
  },
  ...
]

Subscribe to live Websocket feeds

The CAX has a Websocket endpoint for each order book at /orderbooks/<PAIR>/feed:

  • wss://cax.piccadilly.autonity.org/api/orderbooks/ATN-USDC/feed
  • wss://cax.piccadilly.autonity.org/api/orderbooks/NTN-USDC/feed

Each endpoint streams any new trades in that order book as a JSON object.

You can subscribe to an order book feed using your favourite Websocket client. For example, this is how you can subscribe to the trades feed using the websocat command-line client:

$ websocat wss://cax.piccadilly.autonity.org/api/orderbooks/NTN-USDC/feed
{"timestamp":"2024-03-12T19:39:39.818585","price":"10.44","amount":"40000.00"}
{"timestamp":"2024-03-12T19:48:38.095183","price":"10.39","amount":"111111.11"}
{"timestamp":"2024-03-12T19:53:50.810511","price":"10.36","amount":"1000.00"}
...