> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trusset.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Bid on Auction

> Buy collateral from an active Dutch auction at the current price

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.

<Warning>
  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.
</Warning>

## Path Parameters

<ParamField path="marketId" type="string" required>Market ID.</ParamField>

## Body Parameters

<ParamField body="auctionId" type="integer" required>
  Auction ID. Must be a positive integer sent as a JSON number.
</ParamField>

<ParamField body="collateralAmount" type="string" required>
  Collateral to purchase, as a decimal string in collateral token units. Must be greater than zero.
</ParamField>

<ParamField body="txHash" type="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.
</ParamField>

## Response Fields

<ResponseField name="data" type="object">
  <Expandable>
    <ResponseField name="txHash" type="string">Transaction hash. Returned when confirming with `txHash`.</ResponseField>
    <ResponseField name="auctionId" type="integer">Auction ID, echoed back. Returned when confirming with `txHash`.</ResponseField>
    <ResponseField name="collateralPurchased" type="string">Collateral bought, echoed back. Returned when confirming with `txHash`.</ResponseField>
    <ResponseField name="usdcPaid" type="string">Amount paid, in borrow asset units, computed at the price at execution time. Returned when confirming with `txHash`.</ResponseField>
    <ResponseField name="action" type="string">`SIGN_TRANSACTION` when `txHash` is omitted.</ResponseField>
    <ResponseField name="transaction" type="object">`{ to, data }` for the `bidOnAuction` call. Returned when `txHash` is omitted.</ResponseField>
  </Expandable>
</ResponseField>

<Warning>
  The bid transaction is returned alone, with no approval step. The bidder must already have approved the market contract to spend the borrow asset, otherwise the bid reverts.
</Warning>

<Note>
  The price is read at execution, not at quote time, and it falls continuously. The amount actually paid is therefore at or below what you computed from `currentPrice` a moment earlier, never above. Size the approval against the quoted price to leave headroom.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  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"}'
  ```

  ```typescript TypeScript theme={null}
  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
        })
      }
    );
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Calldata Response theme={null}
  {
    "success": true,
    "data": {
      "action": "SIGN_TRANSACTION",
      "transaction": { "to": "0x70A0...", "data": "0x..." },
      "functionName": "bidOnAuction"
    }
  }
  ```

  ```json Confirmed Response theme={null}
  {
    "success": true,
    "data": {
      "txHash": "0xabc...def",
      "auctionId": 3,
      "collateralPurchased": "100",
      "usdcPaid": "11218.000000"
    }
  }
  ```
</ResponseExample>