Trusset Protocol - Infrastructure for Asset Tokenization

POST

lending-external-securities-v2

api

liquidations

{marketId}

bid-on-auction

curl -X POST "https://api.trusset.org/lending-external-securities-v2/api/liquidations/{marketId}/bid-on-auction" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"auctionId": 3, "collateralAmount": "100", "bidder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"}'

const auctionRes = await fetch(
  `https://api.trusset.org/lending-external-securities-v2/api/liquidations/${marketId}/auctions/3`,
  { headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data: auction } = await auctionRes.json();

if (auction.biddable && Number(auction.currentPrice) <= reservePrice) {
  const bidRes = await fetch(
    `https://api.trusset.org/lending-external-securities-v2/api/liquidations/${marketId}/bid-on-auction`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'trusset_your_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        auctionId: 3,
        collateralAmount: auction.collateralRemaining,
        bidder: await bidderWallet.getAddress()
      })
    }
  );
  const { data: bid } = await bidRes.json();
}

{
  "success": true,
  "data": {
    "auctionId": 3,
    "action": "SIGN_TRANSACTIONS",
    "steps": [
      {
        "action": "SIGN_TRANSACTION",
        "transaction": {
          "to": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
          "data": "0x...",
          "value": "0",
          "chainId": 11155111
        },
        "functionName": "approve",
        "description": "Approve the auction venue to pull USDC"
      },
      {
        "action": "SIGN_TRANSACTION",
        "transaction": {
          "to": "0x5c3e8a91d2f04b7e6a1c9d38f0b2e47a6d15c8e3",
          "data": "0x...",
          "value": "0",
          "chainId": 11155111
        },
        "functionName": "bidOnAuction"
      }
    ],
    "venueAddress": "0x5c3e8a91d2f04b7e6a1c9d38f0b2e47a6d15c8e3",
    "bidder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "bidderChecked": true,
    "confirmStepIndex": 1,
    "confirmWith": "bidOnAuction",
    "collateralAmount": "100.0",
    "pricePerUnit": "112.18",
    "estimatedCost": "11218.0",
    "borrowAssetSymbol": "USDC"
  }
}

{
  "success": true,
  "data": {
    "txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
    "auctionId": 3,
    "venueAddress": "0x5c3e8a91d2f04b7e6a1c9d38f0b2e47a6d15c8e3",
    "collateralPurchased": "100.0",
    "amountPaid": "11204.5",
    "bidder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "auctionSettled": false,
    "totalProceeds": null,
    "debtCovered": null,
    "marketLiquidationId": null,
    "shortfall": null,
    "reserve": null
  }
}

{
  "success": true,
  "data": {
    "txHash": "0x4e7a90c2d15b83f6e0a9d4c71b2e58f3a6d09c1e7b45f28a3c6d91e0b7f2a584",
    "auctionId": 3,
    "venueAddress": "0x5c3e8a91d2f04b7e6a1c9d38f0b2e47a6d15c8e3",
    "collateralPurchased": "20.0",
    "amountPaid": "1901.5",
    "bidder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "auctionSettled": true,
    "totalProceeds": "19875.0",
    "debtCovered": "21159.2",
    "marketLiquidationId": "12",
    "shortfall": null,
    "reserve": {
      "requested": "1284.2",
      "covered": "1284.2",
      "uncovered": "0.0"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "AUCTION_EXPIRED",
    "message": "Auction 3 ended at 2024-06-15T11:00:00.000Z (unix 1718449200); bidOnAuction reverts AuctionNotActive after the end time, so no approval or bid is offered. Settle it through the settle-expired-auction path to route the unsold collateral to the liquidation router.",
    "endTime": 1718449200,
    "settleWith": "settle-expired-auction"
  }
}

Purchases collateral from a running auction on the market’s auction venue. The bidder pays in the market’s borrow asset and receives the security tokens. The cost is the collateral quantity multiplied by the auction’s live declining price, rounded up to the next base unit of the borrow asset. Bids can be partial. Buy any quantity up to collateralRemaining, and the auction stays open for the rest until its end time.

The buyer receives a security token, so the token must admit them. Delivery is an ordinary compliance-gated transfer: if the token refuses the bidding wallet, the whole bid reverts and no money moves. Name the bidding wallet as bidder to have the token asked first: a wallet it refuses is answered with 409 BIDDER_CANNOT_RECEIVE instead of calldata. Without bidder the API does not check the wallet, so confirm it is a verified holder on the token’s identity registry before submitting.

When a Bid Reverts

The API prices the bid and refuses auctions that are closed or past their end time. It checks the wallet only when bidder is supplied, and nothing about the market beyond that. The venue reverts the bid in each of these cases:

The market is paused.
The market’s oracle price is stale. The auction’s schedule was fixed when it opened, but the venue still demands a fresh price. Push one through Sync Oracle Price first.
The bidding wallet is the borrower whose collateral is on sale. A borrower cannot buy back their own seized collateral. With bidder, the API refuses this with SELF_PURCHASE_NOT_ALLOWED.
The auction reached its end time between quoting and mining.
The wallet lacks the payment, or the allowance from the first step. With bidder, a short balance is refused with INSUFFICIENT_BALANCE.

Path Parameters

string

required

The market’s record ID, as id on List Markets, not its contract address. See Market IDs.

Body Parameters

integer

required

Auction ID on the market’s venue. Must be a positive integer sent as a JSON number. Required on the confirm call too.

string

required

Collateral to purchase, as a decimal string in collateral token units, with no more decimals than the collateral token has. Must be greater than zero. Required on the confirm call too, although the confirmation reads the purchased amount from the receipt.

string

The wallet that will sign the bid, 0x followed by 40 hex characters. When supplied, the bid is checked against it before any calldata is built. The auction’s borrower is refused with SELF_PURCHASE_NOT_ALLOWED, a borrow asset balance below estimatedCost with INSUFFICIENT_BALANCE, and a wallet the collateral token refuses to receive the collateral from the venue with BIDDER_CANNOT_RECEIVE. When the wallet’s allowance to the venue already covers estimatedCost, the approve step is left out. A balance, allowance or token verdict that cannot be read refuses nothing, and the approve step stays. Not used on the confirm call.

string

Hash of the bidOnAuction transaction you broadcast. Send it with the same auctionId to confirm the bid and record the result. Omit it to receive the calldata.

Sign the Two Steps

Without txHash the response is SIGN_TRANSACTIONS with two steps, or with the bid alone when the allowance of bidder already covers it. Sign them from the bidding wallet, in order, because the venue pulls the payment from the wallet that calls it.

Approve the venue

approve on the borrow asset, naming the auction venue as spender, for estimatedCost. The venue collects the payment, not the market. Left out when the allowance of bidder to the venue already covers estimatedCost.

Bid

bidOnAuction on the venue, for the clamped collateralAmount. Confirm with this step’s hash, which confirmStepIndex names.

What the Closing Bid Settles

The venue forwards each payment to the market straight away, and the market holds it against the liquidation record until the auction closes. The bid that buys the last unit closes the auction. In that same transaction the market settles the record over everything the auction raised. The market keeps at most what the whole position owed at seizure, plus the liquidation penalty (the term penalty on a term realization). Anything above that goes to the borrower, or is escrowed on the market when the settlement token (stablecoin) refuses the transfer. If the proceeds fall short of the record’s claim, the market draws the insurance fund for the gap. Only principal the fund could not cover is booked against the liquidity pool. Only the confirmation of that closing bid carries auctionSettled: true with the settlement figures. Collateral still unsold at the end time is not settled by any bid; it moves to the liquidation router through Settle Expired Auction.

Response Fields

object

Show child attributes

string

SIGN_TRANSACTIONS when txHash is omitted.

integer

Auction the bid targets.

array

The transactions above, each { action, transaction: { to, data, value, chainId }, functionName }. The approve step also carries a description.

string

The market’s auction venue, lowercased. The approval’s spender and the bid’s target.

boolean

true when bidder was supplied, so the borrower, balance and token checks ran against it. false when it was not. Returned when txHash is omitted.

string

Present when bidderChecked is false. Says that the borrower check, the bidder balance and whether the token admits the bidder were not checked before signing.

integer

Index of the step to confirm with: 1, or 0 when the approve step was left out.

string

bidOnAuction.

string

Collateral the bid will buy, clamped to what the auction has left.

string

The auction’s price per whole collateral unit at quote time, in borrow asset units.

string

collateralAmount priced at pricePerUnit, rounded up. The approval is sized to this.

string

Symbol of the asset the bid is paid in.

string

Transaction hash. Returned when confirming with txHash.

string

Collateral actually bought, read from the venue’s bid event, or from the transaction’s own amount when the event cannot be read. Returned when confirming.

string

Amount actually paid, in borrow asset units, at the price in the block the bid mined in. Returned when confirming, null if the bid event could not be read.

string

Wallet that sent the bid, lowercased. When the bid was verified from the receipt log, the address the venue recorded as bidder. Returned when confirming. Without txHash, the bidder you supplied, lowercased, and absent when none was supplied.

boolean

true when this bid bought the last unit, closed the auction and settled the liquidation record. Returned when confirming.

string

Everything the auction raised, settled on the market’s record in this transaction. null unless auctionSettled.

string

The debt the auction was opened against, as the venue’s settlement event reports it. It is not reduced by a shortfall; read shortfall and reserve for that. null unless auctionSettled.

string

The market’s liquidation record the auction settled into. null unless auctionSettled.

string

Principal the liquidity pool absorbed because the proceeds and the insurance fund together fell short. null when there was none, and whenever auctionSettled is false.

object

What the market asked the insurance fund for in this transaction, and what it paid. null when nothing was asked, and whenever auctionSettled is false.

Show child attributes

string

Amount requested from the fund, in borrow asset units.

string

Amount the fund paid.

string

requested minus covered.

array

Present only when the settlement paid or escrowed a surplus for the borrower. Each entry is { kind, loanId, borrower, amount }.

Show child attributes

string

SURPLUS_RETURNED when the surplus reached the borrower. SURPLUS_ESCROWED when the transfer to the borrower was refused and the market holds the amount for the borrower to collect through Claim Surplus.

string

receipt-log, present only when the transaction did not call the venue directly, for example a bid sent through a smart-contract wallet. The API then verified it from the venue’s bid event instead.

string

The contract the transaction actually called. Present with verifiedBy.

string

The wallet that sent the transaction. Present with verifiedBy.

A bid larger than the collateral left is clamped to what remains, and the API prices the clamped amount. collateralAmount and estimatedCost in the response are therefore what the bid will cost, which can be less than you asked for.

The price is read at execution, not at quote time, and it only falls. Another bidder can also take part of the lot first, which shrinks what yours buys. The amount actually paid is therefore at or below estimatedCost, never above, and the approval always covers it.

curl -X POST "https://api.trusset.org/lending-external-securities-v2/api/liquidations/{marketId}/bid-on-auction" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"auctionId": 3, "collateralAmount": "100", "bidder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"}'

const auctionRes = await fetch(
  `https://api.trusset.org/lending-external-securities-v2/api/liquidations/${marketId}/auctions/3`,
  { headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data: auction } = await auctionRes.json();

if (auction.biddable && Number(auction.currentPrice) <= reservePrice) {
  const bidRes = await fetch(
    `https://api.trusset.org/lending-external-securities-v2/api/liquidations/${marketId}/bid-on-auction`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'trusset_your_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        auctionId: 3,
        collateralAmount: auction.collateralRemaining,
        bidder: await bidderWallet.getAddress()
      })
    }
  );
  const { data: bid } = await bidRes.json();
}

{
  "success": true,
  "data": {
    "auctionId": 3,
    "action": "SIGN_TRANSACTIONS",
    "steps": [
      {
        "action": "SIGN_TRANSACTION",
        "transaction": {
          "to": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
          "data": "0x...",
          "value": "0",
          "chainId": 11155111
        },
        "functionName": "approve",
        "description": "Approve the auction venue to pull USDC"
      },
      {
        "action": "SIGN_TRANSACTION",
        "transaction": {
          "to": "0x5c3e8a91d2f04b7e6a1c9d38f0b2e47a6d15c8e3",
          "data": "0x...",
          "value": "0",
          "chainId": 11155111
        },
        "functionName": "bidOnAuction"
      }
    ],
    "venueAddress": "0x5c3e8a91d2f04b7e6a1c9d38f0b2e47a6d15c8e3",
    "bidder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "bidderChecked": true,
    "confirmStepIndex": 1,
    "confirmWith": "bidOnAuction",
    "collateralAmount": "100.0",
    "pricePerUnit": "112.18",
    "estimatedCost": "11218.0",
    "borrowAssetSymbol": "USDC"
  }
}

{
  "success": true,
  "data": {
    "txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
    "auctionId": 3,
    "venueAddress": "0x5c3e8a91d2f04b7e6a1c9d38f0b2e47a6d15c8e3",
    "collateralPurchased": "100.0",
    "amountPaid": "11204.5",
    "bidder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "auctionSettled": false,
    "totalProceeds": null,
    "debtCovered": null,
    "marketLiquidationId": null,
    "shortfall": null,
    "reserve": null
  }
}

{
  "success": true,
  "data": {
    "txHash": "0x4e7a90c2d15b83f6e0a9d4c71b2e58f3a6d09c1e7b45f28a3c6d91e0b7f2a584",
    "auctionId": 3,
    "venueAddress": "0x5c3e8a91d2f04b7e6a1c9d38f0b2e47a6d15c8e3",
    "collateralPurchased": "20.0",
    "amountPaid": "1901.5",
    "bidder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "auctionSettled": true,
    "totalProceeds": "19875.0",
    "debtCovered": "21159.2",
    "marketLiquidationId": "12",
    "shortfall": null,
    "reserve": {
      "requested": "1284.2",
      "covered": "1284.2",
      "uncovered": "0.0"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "AUCTION_EXPIRED",
    "message": "Auction 3 ended at 2024-06-15T11:00:00.000Z (unix 1718449200); bidOnAuction reverts AuctionNotActive after the end time, so no approval or bid is offered. Settle it through the settle-expired-auction path to route the unsold collateral to the liquidation router.",
    "endTime": 1718449200,
    "settleWith": "settle-expired-auction"
  }
}

Error Codes

Code	HTTP	Cause
`MISSING_MARKET_ID`	`400`	The market ID is longer than 100 characters
`NO_MARKET_ADDRESS`	`400`	The market has no on-chain address recorded
`VALIDATION_ERROR`	`400`	`auctionId` is not a positive integer, `collateralAmount` is not a positive decimal string or carries more decimals than the collateral token, `bidder` is not `0x` followed by 40 hex characters, or `txHash` is malformed
`TX_NOT_VERIFIED`	`400`	The confirmed transaction bids on a different auction
`SELF_PURCHASE_NOT_ALLOWED`	`403`	`bidder` is the borrower the venue records for this auction. The venue refuses a borrower buying back its own collateral
`AUCTION_NOT_FOUND`	`404`	The venue has not created an auction with this ID
`MARKET_NOT_FOUND`	`404`	No market with this ID on your instance
`AUCTION_MODULE_NOT_SET`	`409`	The market has no auction venue wired, so no auction can exist on it
`AUCTION_NOT_ACTIVE`	`409`	The auction was fully bought or settled after expiry, or has no collateral left
`AUCTION_EXPIRED`	`409`	The auction passed its end time. The error carries `endTime` and `settleWith`
`INSUFFICIENT_BALANCE`	`409`	`bidder` holds less of the borrow asset than `estimatedCost` at the current auction price
`BIDDER_CANNOT_RECEIVE`	`409`	The collateral token refuses to deliver the auctioned collateral from the venue to `bidder`
`AUCTION_STATE_UNAVAILABLE`	`503`	The auction could not be read on-chain, so the bid could not be priced. Retry shortly

Confirming with txHash can also return any transaction verification error.

curl -X POST "https://api.trusset.org/lending-external-securities-v2/api/liquidations/{marketId}/bid-on-auction" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"auctionId": 3, "collateralAmount": "100", "bidder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"}'

const auctionRes = await fetch(
  `https://api.trusset.org/lending-external-securities-v2/api/liquidations/${marketId}/auctions/3`,
  { headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data: auction } = await auctionRes.json();

if (auction.biddable && Number(auction.currentPrice) <= reservePrice) {
  const bidRes = await fetch(
    `https://api.trusset.org/lending-external-securities-v2/api/liquidations/${marketId}/bid-on-auction`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'trusset_your_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        auctionId: 3,
        collateralAmount: auction.collateralRemaining,
        bidder: await bidderWallet.getAddress()
      })
    }
  );
  const { data: bid } = await bidRes.json();
}

{
  "success": true,
  "data": {
    "auctionId": 3,
    "action": "SIGN_TRANSACTIONS",
    "steps": [
      {
        "action": "SIGN_TRANSACTION",
        "transaction": {
          "to": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
          "data": "0x...",
          "value": "0",
          "chainId": 11155111
        },
        "functionName": "approve",
        "description": "Approve the auction venue to pull USDC"
      },
      {
        "action": "SIGN_TRANSACTION",
        "transaction": {
          "to": "0x5c3e8a91d2f04b7e6a1c9d38f0b2e47a6d15c8e3",
          "data": "0x...",
          "value": "0",
          "chainId": 11155111
        },
        "functionName": "bidOnAuction"
      }
    ],
    "venueAddress": "0x5c3e8a91d2f04b7e6a1c9d38f0b2e47a6d15c8e3",
    "bidder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "bidderChecked": true,
    "confirmStepIndex": 1,
    "confirmWith": "bidOnAuction",
    "collateralAmount": "100.0",
    "pricePerUnit": "112.18",
    "estimatedCost": "11218.0",
    "borrowAssetSymbol": "USDC"
  }
}

{
  "success": true,
  "data": {
    "txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
    "auctionId": 3,
    "venueAddress": "0x5c3e8a91d2f04b7e6a1c9d38f0b2e47a6d15c8e3",
    "collateralPurchased": "100.0",
    "amountPaid": "11204.5",
    "bidder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "auctionSettled": false,
    "totalProceeds": null,
    "debtCovered": null,
    "marketLiquidationId": null,
    "shortfall": null,
    "reserve": null
  }
}

{
  "success": true,
  "data": {
    "txHash": "0x4e7a90c2d15b83f6e0a9d4c71b2e58f3a6d09c1e7b45f28a3c6d91e0b7f2a584",
    "auctionId": 3,
    "venueAddress": "0x5c3e8a91d2f04b7e6a1c9d38f0b2e47a6d15c8e3",
    "collateralPurchased": "20.0",
    "amountPaid": "1901.5",
    "bidder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "auctionSettled": true,
    "totalProceeds": "19875.0",
    "debtCovered": "21159.2",
    "marketLiquidationId": "12",
    "shortfall": null,
    "reserve": {
      "requested": "1284.2",
      "covered": "1284.2",
      "uncovered": "0.0"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "AUCTION_EXPIRED",
    "message": "Auction 3 ended at 2024-06-15T11:00:00.000Z (unix 1718449200); bidOnAuction reverts AuctionNotActive after the end time, so no approval or bid is offered. Settle it through the settle-expired-auction path to route the unsold collateral to the liquidation router.",
    "endTime": 1718449200,
    "settleWith": "settle-expired-auction"
  }
}

Overview

MiCA Register

Customers

Tokenization

Trading

Lending

Operators

Asset Register

Vaults

Seller Financing

Bid on Auction

When a Bid Reverts

Path Parameters

Body Parameters

Sign the Two Steps

What the Closing Bid Settles

Response Fields

Error Codes

​When a Bid Reverts

​Path Parameters

​Body Parameters

​Sign the Two Steps

​What the Closing Bid Settles

​Response Fields

​Error Codes

When a Bid Reverts

Path Parameters

Body Parameters

Sign the Two Steps

What the Closing Bid Settles

Response Fields

Error Codes