Sign in
bids

Submit a new bid

  Submit a bid for a specific auction slot. Validates all critical constraints:
  - Temporal validity (before auction deadline)
  - Economic validity (reserve price, value bounds)
  - Gas constraints (fee_cap >= tip_cap)
  - Entity limits (max bids per slot)
  - Rate limits (max bids per time window)
  - Auction state (must be in bidding state)
post/api/v1/bids

Request body

slotinteger required

Slot number for the bid (must be future slot)

valuestring required
    Bid value in wei (as string for BigInt precision).
    Must be greater than auction reserve price and follow gas constraints.
    Example: "1000000000000000000" = 1 ETH
quantitynumber

Quantity of units to bid for

gasFeeCapstring required

Gas fee cap in wei - must be >= gasTipCap for EIP-1559 compatibility

gasTipCapstring required

Gas tip cap in wei - must be <= gasFeeCap for EIP-1559 compatibility

builderPublicKeystring required

Builder public key for block proposal (0x-prefixed hex string)

metadataobject

Additional bid metadata

Example request

{
  "slot": 1234567,
  "value": "1000000000000000000",
  "quantity": 100,
  "gasFeeCap": "20000000000",
  "gasTipCap": "20000000000",
  "builderPublicKey": "0x1234567890abcdef1234567890abcdef12345678",
  "metadata": {
    "priority": "high",
    "source": "api"
  }
}

Response

Bid submitted successfully

idstring required

Unique bid identifier

slotnumber required

Slot number

entityIdstring required

Entity identifier

valuestring required

Bid value in wei

quantitynumber required

Quantity of units

gasFeeCapstring required

Gas fee cap in wei

gasTipCapstring required

Gas tip cap in wei

builderPublicKeystring required

Builder public key

status'pending' | 'submitted' | 'validated' | 'updated' | 'winning' | 'partial' | 'lost' | 'cancelled' | 'expired' required

Current bid status

submittedAtstring date-time required

Bid submission timestamp

updatedAtstring date-time required

Last update timestamp

validatedAtstring date-time

Validation timestamp

validFromstring date-time required

Bid valid from timestamp

validUntilstring date-time required

Bid valid until timestamp

versionnumber required

Bid version number

noncestring required

Unique nonce for replay protection

metadataobject

Additional bid metadata

isActiveboolean required

Whether bid is currently active

isModifiableboolean required

Whether bid can be modified

hasExpiredboolean required

Whether bid has expired

Example response

{
  "id": "tz4a98xxat96iws9zmbrgj3a",
  "slot": 1234567,
  "entityId": "entity-123",
  "value": "1000000000000000000",
  "quantity": 100,
  "gasFeeCap": "20000000000",
  "gasTipCap": "2000000000",
  "builderPublicKey": "0x1234567890abcdef...",
  "status": "pending",
  "submittedAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z",
  "validatedAt": "2024-01-01T00:00:05.000Z",
  "validFrom": "2024-01-01T00:00:00.000Z",
  "validUntil": "2024-01-01T00:00:12.000Z",
  "version": 1,
  "nonce": "1234567890",
  "metadata": {
    "priority": "high",
    "source": "api"
  },
  "isActive": true,
  "isModifiable": true
}

Changes