Using our API

HttpGateway and theGraph wip

Airsigner's HTTP Gateway Endpoints

HTTP Gateway endpoints are URLs that are used to access and communicate with a specific API or service through the HTTP protocol. These allow clients to perform various actions such as retrieving, updating, and deleting data.

/bid Endpoint

To determine the current price of an asset and evaluate whether a user's position can be liquidated, the searcher can invoke the Airnode's HTTP Gateway endpoint. Once this information has been obtained, the searcher can proceed with executing the liquidation process.

To initiate the liquidation, an HTTP API request must be sent to the Airsigner's /bid endpoint. The searcher places a bid in ETH, indicating how much they are willing to pay for the signed oracle update and the right to liquidate the user. The request format is as follows :

192.168.1.93:33666/bid?key=APIKEY&endpoint=ENDPOINT&amount=AMOUNT&searcher=ADDRESS&chain=CHAINID

In addition to the query terms, it's necessary to send API3 specific encoded parameters that the data provider needs in the request's body using POST method.

CONFIRMATION When you bid on an auction, you’ll get a response like this as confirmation :

{
   "result": "received",
   "auction_start": "1661068030",
   "encoded_parameters": "0x3173000000000000000000000000000000000000000000000000000000000000636f696e49640000000000000000000000000000000000000000000000000000657468657265756d000000000000000000000000000000000000000000000000",
   "endpoint_id":"0xa61b14539710378cdcc0723d8818c69670225ffefdcb192663216fb69760e7d9",
   "searcher": "0x49a4C3E14CF0416276a17F4af2d4119BDBE67FF9",
   "amount":"8757790000000000000",
   "auction_id":"0x0042594afe0b038517f38b36e4b5a658dacafdeea995045935150de89d59f12c",
   "chain_id": "1"
}

/win Endpoint

Once the auction timer ends, each searcher who placed a bid must check the /win endpoint and see if they won. Remember the auction is a sealed-bid, so users won’t know who else bid, how much they bid, or any other details. The output will either return :

• Auction details and a signature.

  OR

• A message that the user did not win.

CONFIRMATION A winning response looks like this :

{                       "signature":"0xa61b14539710378cdcc0723d8818c69670225ffefdcb192663216fb69760e7d9d3739ef1736bee5de09c7c77fd7d277fd4fa3e3fe94add99d6bab54f69f10389",
   "price":"157920000000",
   "price_decimals": "8",
   "timestamp": "1661068030",
   "beacon_id":"0xe28b337f0b4e342dced291089f2f3ffa781cbf653bc2e90fe6552aab7523af8a",
   "user": "0x49a4C3E14CF0416276a17F4af2d4119BDBE67FF9",
   "chain_id": "1",
   "amount": "8757790000000000000",
   "auction_id":"0x0042594afe0b038517f38b36e4b5a658dacafdeea995045935150de89d59f12c"
}

The crucial aspect to take into account is the signature value, which is a hash of all the auction parameters, including price, timestamp, and other relevant information, that is signed by Airsigner's private key.

The signature is then transmitted by the MEV searcher to the airsignerLiquidate() function within the Perped smart contract. Settlement is a struct, then there is the price, the timestamp, the asset(what the price is for), and the signature(ensures the data came from Airsigner).

function airsignerLiquidate(Settlement calldata settlement, uint256 price, uint256 timestamp, string memory asset, bytes calldata signature) external {
        ...;
}

Decoding

The signature and data can be decoded by another function using a few solidity built-ins and hashing functions :

function _decode_verify_httpgw_data(uint256 price, uint256 timestamp, string memory asset, bytes calldata signature) internal view returns(uint256) {
      require((keccak256(abi.encodePacked(price, timestamp, asset)).toEthSignedMessageHash()).recover(signature) == airnode, "Signature mismatch");
      require(timestamp > block.timestamp, "Price in the past?");
      require(price > 0, "negative price?");
      return price;
}

After a few checks, the _decode_verify_httpgw_data() function returns the price back to the airsignerLiquidate() function and the affected user’s perpetual position is essentially closed.

A set amount of fees are collected from their remaining collateral and split between the protocol and the MEV searcher, anything left is credited back to the user via the Perped protocol’s currency pool contract. Once this happens, accounts have now been settled.

Note

The Airsigner project is still in development however, and the final release may look slightly different than this. Furthermore an admin liquidation function exists so the Perped team can run their own keeper and ensure prompt liquidations should Airsigner not be functioning or available.