Dutch Auctions
Bid on Auction
Buy collateral from an active Dutch auction at the current price
POST
/
lending-external-securities
/
api
/
liquidations
/
{marketId}
/
bid-on-auction
curl -X POST "https://api.trusset.org/lending-external-securities/api/liquidations/{marketId}/bid-on-auction" \
-H "X-API-Key: trusset_your_key_here" \
-H "Content-Type: application/json" \
-d '{"auctionId": 3, "collateralAmount": "100"}'
const auctionRes = await fetch(
`https://api.trusset.org/lending-external-securities/api/liquidations/${marketId}/auctions/3`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data: auction } = await auctionRes.json();
if (Number(auction.currentPrice) <= reservePrice) {
await fetch(
`https://api.trusset.org/lending-external-securities/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
})
}
);
}
{
"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 market to pull USDC"
},
{
"action": "SIGN_TRANSACTION",
"transaction": {
"to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
"data": "0x...",
"value": "0",
"chainId": 11155111
},
"functionName": "bidOnAuction"
}
],
"confirmStepIndex": 1,
"confirmWith": "bidOnAuction",
"collateralAmount": "100.000000000000000000",
"pricePerUnit": "112.180000",
"estimatedCost": "11218.000000",
"borrowAssetSymbol": "USDC"
}
}
{
"success": true,
"data": {
"txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
"auctionId": 3,
"collateralPurchased": "100.000000000000000000",
"amountPaid": "11204.500000",
"bidder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"
}
}
{
"success": false,
"error": {
"code": "AUCTION_NOT_ACTIVE",
"message": "Auction 3 is not active — it was fully bought, settled after expiry, or never existed. Bidding on it reverts, so no transaction is offered."
}
}
Purchases collateral from an open auction. The bidder pays in the market’s borrow asset and receives the security tokens. Cost is the collateral quantity multiplied by the auction’s live declining price.
Bids can be partial. Buy any quantity up to
collateralRemaining, and the auction stays open for the rest.
The buyer receives an ERC-3643 security token, so they must satisfy its compliance rules. A bid from an unverified address reverts on transfer. Confirm the bidder is a verified holder on the token’s identity registry before submitting.
Path Parameters
string
required
Market ID.
Body Parameters
integer
required
Auction ID. Must be a positive integer sent as a JSON number.
string
required
Collateral to purchase, as a decimal string in collateral token units. Must be greater than zero.
string
Hash of the transaction you broadcast for this operation. Send it to confirm the transaction and record the result. Omit it to receive the calldata.
Response Fields
object
Show child attributes
Show child attributes
string
SIGN_TRANSACTIONS when txHash is omitted.integer
Auction the payload bids on.
array
Ordered transactions. The first approves the market to pull the borrow asset for the priced cost of this bid, the second calls
bidOnAuction.integer
Index of the step to confirm with. Always
1.string
bidOnAuction.string
Collateral the bid will actually buy, clamped to what the auction has left.
string
The auction’s live price per collateral unit, in borrow asset units.
string
collateralAmount priced at pricePerUnit. The approval step 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 receipt. Returned when confirming with
txHash.string
Amount actually paid, in borrow asset units, at the price at execution time. Returned when confirming with
txHash.string
Address that signed the bid. Returned when confirming with
txHash.A bid larger than the collateral left is clamped by the contract to what remains, and the API prices the clamped amount.
collateralAmount and estimatedCost in the response are therefore what the bid will actually cost, which can be less than what you asked for.The price is read at execution, not at quote time, and it falls continuously. The amount actually paid is therefore at or below
estimatedCost, never above.curl -X POST "https://api.trusset.org/lending-external-securities/api/liquidations/{marketId}/bid-on-auction" \
-H "X-API-Key: trusset_your_key_here" \
-H "Content-Type: application/json" \
-d '{"auctionId": 3, "collateralAmount": "100"}'
const auctionRes = await fetch(
`https://api.trusset.org/lending-external-securities/api/liquidations/${marketId}/auctions/3`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data: auction } = await auctionRes.json();
if (Number(auction.currentPrice) <= reservePrice) {
await fetch(
`https://api.trusset.org/lending-external-securities/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
})
}
);
}
{
"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 market to pull USDC"
},
{
"action": "SIGN_TRANSACTION",
"transaction": {
"to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
"data": "0x...",
"value": "0",
"chainId": 11155111
},
"functionName": "bidOnAuction"
}
],
"confirmStepIndex": 1,
"confirmWith": "bidOnAuction",
"collateralAmount": "100.000000000000000000",
"pricePerUnit": "112.180000",
"estimatedCost": "11218.000000",
"borrowAssetSymbol": "USDC"
}
}
{
"success": true,
"data": {
"txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
"auctionId": 3,
"collateralPurchased": "100.000000000000000000",
"amountPaid": "11204.500000",
"bidder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"
}
}
{
"success": false,
"error": {
"code": "AUCTION_NOT_ACTIVE",
"message": "Auction 3 is not active — it was fully bought, settled after expiry, or never existed. Bidding on it reverts, so no transaction is offered."
}
}
Error Codes
| Code | HTTP | Cause |
|---|---|---|
NO_MARKET_ADDRESS | 400 | The market has no on-chain address recorded |
VALIDATION_ERROR | 400 | auctionId is not a positive integer, or collateralAmount is not a positive decimal string |
TX_NOT_VERIFIED | 400 | The confirmed transaction bids on a different auction |
MARKET_NOT_FOUND | 404 | No market with this ID on your instance |
AUCTION_NOT_ACTIVE | 409 | The auction was fully bought, settled after expiry, has no collateral left, or never existed |
AUCTION_STATE_UNAVAILABLE | 503 | The auction could not be read on-chain, so the bid could not be priced. Retry shortly |
⌘I
curl -X POST "https://api.trusset.org/lending-external-securities/api/liquidations/{marketId}/bid-on-auction" \
-H "X-API-Key: trusset_your_key_here" \
-H "Content-Type: application/json" \
-d '{"auctionId": 3, "collateralAmount": "100"}'
const auctionRes = await fetch(
`https://api.trusset.org/lending-external-securities/api/liquidations/${marketId}/auctions/3`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data: auction } = await auctionRes.json();
if (Number(auction.currentPrice) <= reservePrice) {
await fetch(
`https://api.trusset.org/lending-external-securities/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
})
}
);
}
{
"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 market to pull USDC"
},
{
"action": "SIGN_TRANSACTION",
"transaction": {
"to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
"data": "0x...",
"value": "0",
"chainId": 11155111
},
"functionName": "bidOnAuction"
}
],
"confirmStepIndex": 1,
"confirmWith": "bidOnAuction",
"collateralAmount": "100.000000000000000000",
"pricePerUnit": "112.180000",
"estimatedCost": "11218.000000",
"borrowAssetSymbol": "USDC"
}
}
{
"success": true,
"data": {
"txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
"auctionId": 3,
"collateralPurchased": "100.000000000000000000",
"amountPaid": "11204.500000",
"bidder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"
}
}
{
"success": false,
"error": {
"code": "AUCTION_NOT_ACTIVE",
"message": "Auction 3 is not active — it was fully bought, settled after expiry, or never existed. Bidding on it reverts, so no transaction is offered."
}
}