API endpoints for positions management on Aqua

BASE API URL for testing: https://newapi.native.org/swap-api/v1

  • headers: api_key:<mm_apiKey>

  1. GET /aqua/mm-settings

Get mm settings data that includes information such as additional credit limit, pause status, and liquidation factor.

Query params

  • address : mm address

  • chain: Native blockchain name, ex: ethereum , bsc , etc

Example response

// Success
{
    "mm_address": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63",
    "mm_partner": "testPmm",
    "hard_limit_usd_threshold": 10000, //additional credit limit on top of collateral
    "token_amount_limit": null,
    "is_forced_paused": false, //force paused by admin from all activities
    "is_paused": false, //pause borrowing because of time delay of settlement or collateral removal
    "is_interest_paused": false,
    "liquidation_factor": 0.8,
    "leverage": 10, //leverage factor to decide max position that MM can open
}

// Missing or invalid params
{
    "statusCode": 404,
    "message": "MM Settings not found",
    "error": "Not Found"
}

  1. GET /aqua/token-settings

Get aqua related token settings such as short fee, long fee, and collateral factor

Query params

  • chain: Native blockchain name, ex: ethereum , bsc , etc

Example response

// Success
[
    {
        "id": 9,
        "token_address": "0x4200000000000000000000000000000000000006",
        "lp_token_address": "0x8D31975B480318295A9Dd74e6ACeD206B7464b08",
        "token_group": null,
        "token_symbol": "WETH",
        "chain": "base",
        "collateral_factor": 1,
        "short_fee_bips": 300,
        "long_fee_bips": 100,
        "cex_symbol": "ETH"
    },
    {
        "id": 10,
        "token_address": "0xd9aAEc86B65D86f6A7B5B1b0c42FFA531710b6CA",
        "lp_token_address": "0x5d55432c6aAeDB4D34523B2744e959F03aEffFE3",
        "token_group": null,
        "token_symbol": "USDbC",
        "chain": "base",
        "collateral_factor": 0.95,
        "short_fee_bips": 1100,
        "long_fee_bips": 500,
        "cex_symbol": "USDC"
    }
]

// Missing or invalid chain param
[]

  1. GET /aqua/mm-positions

Get current mm position for the specific chain. Note that there will be a time delay of 1 minute to 2 minute before Market Maker position is updated

Query params

  • address : mm address

  • chain: Native blockchain name, ex: ethereum , bsc , etc

Example response

// Success
{
    "overallCreditUsd": 9.578294408078364, //current credit USD position
    "limitCreditUsd": -8000, //total limit = (hard limit + collateral) * liquidation factor
    "creditItems": [
        {
            "tokenAddress": "0xed3b4cf471e574ec44903fad3874781b8b84af5e",
            "tokenSymbol": "WETH",
            "mmAddress": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63",
            "chain": "bsc_testnet",
            "tokenUsdPrice": 2259.978181987661,
            "collateralFactor": 1,
            "amount": "1000000000000000000",
            "amountEther": 1,
            "amountUsd": 2259.978181987661,
            "pendingFee": "570776255707762",
            "pendingFeeEther": 0.0005707762557077625,
            "pendingFeeUsd": 1.2899418846961537,
            "creditUsd": 2261.268123872357 //(amountUsd + pendingFeeUsd) * collateralFactor (for long)
        },
        {
            "tokenAddress": "0x2a5bf6854ca6c236d190b7cfe206457b8d46506c",
            "tokenSymbol": "USDT",
            "mmAddress": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63",
            "chain": "bsc_testnet",
            "tokenUsdPrice": 1.0008453164605216,
            "collateralFactor": 0.95,
            "amount": "-2249017835008475200000",
            "amountEther": -2249.0178350084752,
            "amountUsd": -2250.9189668044146,
            "pendingFee": "-770211587331669601",
            "pendingFeeEther": -0.7702115873316696,
            "pendingFeeUsd": -0.7708626598645255,
            "creditUsd": -2251.689829464279  //(amountUsd + pendingFeeUsd) * collateralFactor (for long)
        }
    ],
    "collateralItems": [],
    "pendingRequest": {
	"id": "83048181-b55b-4385-a595-d5008a9f6686",
        "nonce": "1009029896477241",
        "recipient": "0xff8Ba4D1fC3762f6154cc942CCF30049A2A0cEC6",
        "chain": "bsc_testnet",
        "positionUpdates": [
            {
                "tokenAddress": "0x4200000000000000000000000000000000000006",
                "amount": "-2500000000000000"
            }
        ],
        "trader": "0xff8Ba4D1fC3762f6154cc942CCF30049A2A0cEC6",
        "requestAt": "2024-01-30T08:15:04.831Z",
        "enableAt": "2024-01-30T08:20:04.831Z",
        "expiresAt": "2024-01-30T08:21:04.834Z",
        "type": "settlement",
        "creditChangeUsd": -5.770350394917008
		},
    "chain": "bsc_testnet",
    "timestamp": 1704446520094
}

// Missing or invalid chain param
{}

  1. GET /aqua/mm-available-borrow

Get all borrowable token and max token amount that MM is able to borrow from aqua. The token amount depends on the collateral amount, max leverage, and available token in aqua vault.

Query params

  • address : mm address

  • chain: Native blockchain name, ex: ethereum , bsc , etc

Response

{
    "0x4200000000000000000000000000000000000006": {
        "maxBorrowAmount": "102500000000000000",
        "maxBorrowAmountEther": 0.1025,
        "tokenUsd": 2852.2094014285335
    },
    "0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca": {
        "maxBorrowAmount": "253995018",
        "maxBorrowAmountEther": 253.995018,
        "tokenUsd": 0.9995385335714285
    }
}

  1. POST /aqua/verify-settlement

In order to do settlement, Market maker will be paused from further trading and collateral removal activities to make sure that the credit is still healthy after the settlement is done. There will be a time delay of 10 minutes before you are able to get the approval signature to do settlement and execute it within an expire time.

steps to do settlement

  • call /aqua/verify-settlement endpoint to make sure your settlement request is valid

  • call /aqua/request-settlement endpoint to create settlement request and start the time delay. Note that Market Maker will be paused at this point from other activities.

  • call /aqua/cancel-settlement endpoint to cancel settlement request and unpause the trading activities.

  • call /aqua/settlement-status endpoint to check the status of the time delay and get the signature calldata if the time delay has been passed.

Request body

{
    "chain": "bsc_testnet", //use Native blockchain name
    "recipient": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63",
    "positionUpdates": [{
        "tokenAddress": "0x2a5bf6854ca6c236d190b7cfe206457b8d46506c",
        "amount": "1000000000000000000"
    }],
    "trader": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63"
}

  • note that: positive amount means you want to close short position by depositing money in, negative amount means you want to close long position by withdraw the money out

Example response

// Success
{
    "id": "d49c39ed-ff63-41c0-bf3a-75f6d56f7346",
    "nonce": "6168514449590345",
    "recipient": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63",
    "chain": "base",
    "positionUpdates": [
        {
            "tokenAddress": "0x4200000000000000000000000000000000000006",
            "amount": "-5000000000"
        }
    ],
    "creditChangeUsd": -0.00001168615,
    "trader": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63",
    "requestAt": "2024-01-31T08:09:22.645Z",
    "enableAt": "2024-01-31T08:14:22.645Z",
    "expiresAt": "2024-01-31T08:15:22.645Z",
    "type": "settlement"
}

// Errors
// Try to withdraw more than long position amount
{
    "statusCode": 400,
    "message": "Cannot make long position to become short position",
    "error": "Bad Request"
}

// Try to deposit into long position
{
    "statusCode": 400,
    "message": "Cannot increasing existing long position",
    "error": "Bad Request"
}

// Try to deposit more than short position amount
{
    "statusCode": 400,
    "message": "Cannot make short position to become long position",
    "error": "Bad Request"
}

// Try to withdraw from short position
{
    "statusCode": 400,
    "message": "Cannot decreasing existing short position",
    "error": "Bad Request"
}

// Invalid token address
{
    "statusCode": 400,
    "message": "Cannot settle unexist position",
    "error": "Bad Request"
}

// Invalid mm
{
    "statusCode": 404,
    "message": "MM Settings not found",
    "error": "Not Found"
}

  1. POST /aqua/request-settlement

Request settlement

Request body

{
    "chain": "bsc_testnet", //use Native blockchain name
    "recipient": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63",
    "positionUpdates": [{
        "tokenAddress": "0x2a5bf6854ca6c236d190b7cfe206457b8d46506c",
        "amount": "1000000000000000000"
    }],
    "trader": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63"
}

Example response

// Success
{
    "status": "success",
    "id": "b9292014-1e85-43e8-a635-8a4f1c5423b9"
}

// Errors
// Pending request
{
    "statusCode": 400,
    "message": "Settlement request exists, please cancel previous request!",
    "error": "Bad Request"
}

// Other error messages same as in /aqua/verify-settlement

  1. POST /aqua/cancel-settlement

Cancel pending settlement request

Request body

{
    "chain": "bsc_testnet", //use Native blockchain name
    "trader": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63"
}

Response body

// Success
{
    "status": "success",
    "id": "b9292014-1e85-43e8-a635-8a4f1c5423b9"
}

// Error (no request made)
{
    "statusCode": 400,
    "message": "Settlement request not found",
    "error": "Bad Request"
}

  1. POST /aqua/settlement-status

Get status of the settlement request. If the time delay has been passed, the signature calldata will be returned

Request body

{
    "chain": "bsc_testnet", //use Native blockchain name
    "trader": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63"
}

Response body

// During time delay
{
    "status": "pending",
    "readyAt": "2024-01-31T07:12:26.976Z",
    "expiresAt": "2024-01-31T07:13:26.976Z"
}

// Ready
{
    "status": "ready",
    "readyAt": "2024-01-08T02:03:15.635Z",
    "expiresAt": "2024-01-08T02:04:15.636Z",
    "data": {
        "request": {
            "nonce": 2136417542436379,
            "deadline": 1704679455,
            "positionUpdates": [
                {
                    "tokenAddress": "0x2A5Bf6854cA6c236D190b7cfE206457B8d46506C",
                    "amount": "200000000000000000000"
                }
            ]
        },
        "signature": "0x4ea3518372d87cebd8dc869062648b717aac4ba49766967afe4747023d619ce626eefe7be09ab5866b3977e1654af355c2bf80550386d82de4d123d0c70291a31b",
        "recipient": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63",
        "txRequest": {
            "to": "0xC71a906A4B0721E58fC36314474334FdB2bAB937",
            "value": "0",
            "calldata": "0x4339a57d000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000001200000000000000000000000009b85b4a413efe69684290816a3e814b4aa1eff630000000000000000000000000000000000000000000000000007970f78b5761b00000000000000000000000000000000000000000000000000000000659b581f000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000010000000000000000000000002a5bf6854ca6c236d190b7cfe206457b8d46506c00000000000000000000000000000000000000000000000ad78ebc5ac620000000000000000000000000000000000000000000000000000000000000000000414ea3518372d87cebd8dc869062648b717aac4ba49766967afe4747023d619ce626eefe7be09ab5866b3977e1654af355c2bf80550386d82de4d123d0c70291a31b00000000000000000000000000000000000000000000000000000000000000"
        }
    }
}

// Expired
{
    "status": "expired",
    "readyAt": "2024-01-31T07:12:26.976Z",
    "expiresAt": "2024-01-31T07:13:26.976Z"
}

// Error (no request made)
{
    "statusCode": 400,
    "message": "No request has been made",
    "error": "Bad Request"
}

  1. POST /aqua/verify-collateral-removal

In order to do collateral removal, Market maker will be paused from further trading and settlement activities to make sure that the credit is still healthy after the collateral is removed. There will be a time delay of 10 minutes before you are able to get the approval signature to remove your collateral and execute it within an expire time.

steps to do collateral removal

  • call /aqua/verify-collateral-removal endpoint to make sure your request is valid

  • call /aqua/request-collateral-removal endpoint to create collateral removal request and start the time delay. Note that Market Maker will be paused at this point from other activities.

  • call /aqua/cancel-collateral-removal endpoint to cancel settlement request and unpause the trading activities.

  • call /aqua/collateral-removal-status endpoint to check the status of the time delay and get the signature calldata if the time delay has been passed.

Request body

{
    "chain": "bsc_testnet",
    "recipient": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63",
    "tokens": [{
        "tokenAddress": "0x2A5Bf6854cA6c236D190b7cfE206457B8d46506C", //lp Token address
        "amount": "200000000000000000000"
    }],
    "trader": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63"
}

Response body

// Success
{
    "id": "673a69b0-06db-4309-b0f1-6582435b80ca",
    "nonce": "6885024828728157",
    "recipient": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63",
    "chain": "base",
    "tokens": [
        {
            "tokenAddress": "0x5d55432c6aAeDB4D34523B2744e959F03aEffFE3",
            "amount": "10000000000000000000"
        }
    ],
    "totalCollateralRemovedUsd": 9.778953854000001e-12,
    "trader": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63",
    "requestAt": "2024-01-31T09:17:41.847Z",
    "enableAt": "2024-01-31T09:22:41.847Z",
    "expiresAt": "2024-01-31T09:23:41.847Z",
    "type": "collateralRemoval"
}

// Errors
// Invalid token
{
    "statusCode": 400,
    "message": "Collateral does not exist for token 0x12345",
    "error": "Bad Request"
}

// Insufficient collateral
{
    "statusCode": 400,
    "message": "Collateral amount is not enough for token 0x5d55432c6aAeDB4D34523B2744e959F03aEffFE3",
    "error": "Bad Request"
}

// Invalid mm
{
    "statusCode": 404,
    "message": "MM Settings not found",
    "error": "Not Found"
}

  1. POST /aqua/request-collateral-removal

Request collateral removal

Request body

{
    "chain": "bsc_testnet", //use Native blockchain name
    "recipient": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63",
    "positionUpdates": [{
        "tokenAddress": "0x2a5bf6854ca6c236d190b7cfe206457b8d46506c", //lp Token address
        "amount": "1000000000000000000"
    }],
    "trader": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63"
}

Response body

// Success
{
    "success": true,
    "id": "ffa84899-3c76-4e2b-a720-10c5d9bc0da0"
}

// Errors
// Pending request
{
    "statusCode": 400,
    "message": "Pending request exists, please cancel previous request!",
    "error": "Bad Request"
}

// error messages same as in /aqua/verify-collateral-removal

  1. POST /aqua/cancel-collateral-removal

Cancel pending collateral removal

Request body

{
    "chain": "bsc_testnet", //use Native blockchain name
    "trader": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63"
}

Response body

// Success
{
    "success": true
}

// Error
{
    "statusCode": 400,
    "message": "Collateral removal request not found",
    "error": "Bad Request"
}

  1. POST /aqua/collateral-removal-status

Get status of the collateral removal request. If the time delay has been passed, the signature calldata will be returned

Request body

{
    "chain": "bsc_testnet", //use Native blockchain name
    "trader": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63"
}

Response body

// During time delay
{
    "status": "pending",
    "readyAt": "2024-01-31T09:39:15.776Z",
    "expiresAt": "2024-01-31T09:40:15.776Z"
}

// Ready
{
    "status": "ready",
    "readyAt": "2024-01-08T02:03:15.635Z",
    "expiresAt": "2024-01-08T02:04:15.636Z",
    "data": {
        "request": {
            "nonce": 2136417542436379,
            "deadline": 1704679455,
            "positionUpdates": [
                {
                    "tokenAddress": "0x2A5Bf6854cA6c236D190b7cfE206457B8d46506C",
                    "amount": "200000000000000000000"
                }
            ]
        },
        "signature": "0x4ea3518372d87cebd8dc869062648b717aac4ba49766967afe4747023d619ce626eefe7be09ab5866b3977e1654af355c2bf80550386d82de4d123d0c70291a31b",
        "recipient": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63",
        "txRequest": {
            "to": "0xC71a906A4B0721E58fC36314474334FdB2bAB937",
            "value": "0",
            "calldata": "0x4339a57d000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000001200000000000000000000000009b85b4a413efe69684290816a3e814b4aa1eff630000000000000000000000000000000000000000000000000007970f78b5761b00000000000000000000000000000000000000000000000000000000659b581f000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000010000000000000000000000002a5bf6854ca6c236d190b7cfe206457b8d46506c00000000000000000000000000000000000000000000000ad78ebc5ac620000000000000000000000000000000000000000000000000000000000000000000414ea3518372d87cebd8dc869062648b717aac4ba49766967afe4747023d619ce626eefe7be09ab5866b3977e1654af355c2bf80550386d82de4d123d0c70291a31b00000000000000000000000000000000000000000000000000000000000000"
        }
    }
}

// Expired
{
    "status": "expired",
    "readyAt": "2024-01-31T09:39:15.776Z",
    "expiresAt": "2024-01-31T09:40:15.776Z"
}

// Error (no request made)
{
    "statusCode": 400,
    "message": "No request has been made",
    "error": "Bad Request"
}

  1. POST /aqua/liquidation

Whitelisted liquidator can request for Marker Maker liquidation by specify what position they want to close and how much collateral they want to claim. Liquidator can do partial liquidation as long as the Market Maker credit health is increasing.

Request body

{
    "chain": "bsc_testnet",
    "recipient": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63",
    "positionUpdates": [{
        "tokenAddress": "0x2a5bf6854ca6c236d190b7cfe206457b8d46506c",
        "amount": "1778215747139230000000"
    }],
    "claimCollaterals": [{
        "tokenAddress": "0x2a5bf6854ca6c236d190b7cfe206457b8d46506c",
        "amount": "1000000000000000000000"
    }],
    "trader": "0x9B85B4A413Efe69684290816a3E814B4aA1EFf63"
}

  • Note that for position updates: positive amount means you want to close short position by depositing money in, negative amount means you want to close long position by withdraw the money out.

  • claim collateral amount is always positive meaning how much collateral amount you want to claim

  1. GET /aqua/all-mm-settings

return all mm address and the chain they are in.

Query params

  • liquidator : whitelisted liquidator address

response

[
    {
        "mm_address": "0x54083336251a609e79c7f8ebb6180b7ef5f96402",
        "chains": [
            "base"
        ]
    },
    {
        "mm_address": "0xff8ba4d1fc3762f6154cc942ccf30049a2a0cec6",
        "chains": [
            "base"
        ]
    }
]

Contract Call for Market Maker

common structs reference

struct TokenAmountUint {
    address tokenAddress;
    uint amount;
}

struct TokenAmountInt {
    address tokenAddress;
    int amount;
}

  1. addCollateral

    note: uses >100k gas

    function addCollateral(TokenAmountUint[] calldata tokens, address trader);

    1. AquaVault takes in LP token to serve as collateral for trading

    2. MM needs to give allowance in advance

      1. Approve LP token on ERC20 token in order to call mint

      2. Approve AquaVault on LP token to call addCollateral

  2. removeCollateral

    1. MM needs to call Native API with the remove amounts to get the signature to execute the transaction

    // nonce, deadline and signature are returned by API
struct RemoveCollateralRequest {
    uint nonce;
    uint deadline;
    TokenAmountUint[] tokens;
}

function removeCollateral(
    RemoveCollateralRequest calldata request,
    bytes calldata signature,
    address recipient
)

  3. repay

    function repay(TokenAmountUint[] calldata repayments);

    1. MM repays the short positions to decrease the open position

    2. No signature needed

  4. settle

    1. MM needs to call Native API with the settlement proposal to get the signature for sending the settlement transaction

    // nonce, deadline and signature are returned by API
struct SettlementRequest {
    uint nonce;
    uint deadline;
    TokenAmountInt[] positionUpdates;
}

function settle(
    SettlementRequest calldata request,
    bytes calldata signature,
    address recipient
)

  5. liquidate

    1. MM needs to call Native API with the liquidation proposal to get the signature for sending the liquidation transaction

    2. only whitelisted liquidator can request for liquidation

      struct LiquidationRequest {
    uint nonce;
    uint deadline;
    address trader;
    TokenAmountInt[] positionUpdates;
    TokenAmountUint[] claimCollaterals;
}

function liquidate(
    LiquidationRequest calldata request,
    bytes calldata signature,
    address recipient
)
PreviousChanges needed for market maker quote on Aqua inventoryNextFAQ

Last updated