Submit a new bid

Submit a bid for a specific auction slot.

Critical Constraints

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)

Authorization

Request Body

slotinteger

Slot number for the bid (must be future slot)

Range1 <= value

valuestring

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

Match^[0-9]+$

quantity?number

Quantity of units to bid for

Default1

Range1 <= value

gasFeeCapstring

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

Match^[0-9]+$

gasTipCapstring

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

Match^[0-9]+$

builderPublicKeystring

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

Match^0x[a-fA-F0-9]+$

Length42 <= length <= 132

metadata?object

Additional bid metadata

Empty Object

Response Body

curl -X POST "http://localhost:3000/api/v1/bids" \
  -H "Content-Type: application/json" \
  -d '{
    "slot": 1234567,
    "value": "1000000000000000000",
    "gasFeeCap": "20000000000",
    "gasTipCap": "20000000000",
    "builderPublicKey": "0x1234567890abcdef1234567890abcdef12345678"
  }'

const body = JSON.stringify({
  "slot": 1234567,
  "value": "1000000000000000000",
  "gasFeeCap": "20000000000",
  "gasTipCap": "20000000000",
  "builderPublicKey": "0x1234567890abcdef1234567890abcdef12345678"
})

fetch("http://localhost:3000/api/v1/bids", {
  body
})

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
  "strings"
)

func main() {
  url := "http://localhost:3000/api/v1/bids"
  body := strings.NewReader(`{
    "slot": 1234567,
    "value": "1000000000000000000",
    "gasFeeCap": "20000000000",
    "gasTipCap": "20000000000",
    "builderPublicKey": "0x1234567890abcdef1234567890abcdef12345678"
  }`)
  req, _ := http.NewRequest("POST", url, body)
  req.Header.Add("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import requests

url = "http://localhost:3000/api/v1/bids"
body = {
  "slot": 1234567,
  "value": "1000000000000000000",
  "gasFeeCap": "20000000000",
  "gasTipCap": "20000000000",
  "builderPublicKey": "0x1234567890abcdef1234567890abcdef12345678"
}
response = requests.request("POST", url, json = body, headers = {
  "Content-Type": "application/json"
})

print(response.text)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Duration;
import java.net.http.HttpRequest.BodyPublishers;

var body = BodyPublishers.ofString("""{
  "slot": 1234567,
  "value": "1000000000000000000",
  "gasFeeCap": "20000000000",
  "gasTipCap": "20000000000",
  "builderPublicKey": "0x1234567890abcdef1234567890abcdef12345678"
}""");
HttpClient client = HttpClient.newBuilder()
  .connectTimeout(Duration.ofSeconds(10))
  .build();

HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
  .uri(URI.create("http://localhost:3000/api/v1/bids"))
  .header("Content-Type", "application/json")
  .POST(body)
  .build();

try {
  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());
  System.out.println("Status code: " + response.statusCode());
  System.out.println("Response body: " + response.body());
} catch (Exception e) {
  e.printStackTrace();
}

using System;
using System.Net.Http;
using System.Text;

var body = new StringContent("""
{
  "slot": 1234567,
  "value": "1000000000000000000",
  "gasFeeCap": "20000000000",
  "gasTipCap": "20000000000",
  "builderPublicKey": "0x1234567890abcdef1234567890abcdef12345678"
}
""", Encoding.UTF8, "application/json");

var client = new HttpClient();
var response = await client.PostAsync("http://localhost:3000/api/v1/bids", body);
var responseBody = await response.Content.ReadAsStringAsync();

{
  "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,
  "hasExpired": false
}

Empty

Submit a new bid

Authorization

Request Body

Response Body

201

400

404