Fill Endpoints

Fill endpoints handle the recording of completed on-chain trades and retrieval of fill history. When a trade is settled on-chain, the fill is recorded with points computation and venue benchmark comparison.

Record Fill (Public)

POST /api/v1/fills

Records a completed RFQ fill after on-chain settlement. Computes price improvement against the AMM baseline and awards points to both taker and maker.

Request Body

Example Request

const res = await fetch("https://hyperquote.xyz/api/v1/fills", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    txHash: "0xabc123def456789...",
    rfqId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    taker: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
    maker: "0xAbCd1234567890abcdef1234567890abcdef1234",
    tokenIn: "0xb88339cb...",
    tokenOut: "0x55555555...",
    amountIn: "1000000000",
    amountOut: "50000000000000000000",
    amountInUsd: 1000.0,
    visibility: "public",
  }),
});

Response (200 OK)

{
  "success": true,
  "fill": {
    "id": "clx9fill123...",
    "txHash": "0xabc123def456789...",
    "improvementBps": 150,
    "takerPoints": 125.5,
    "makerPoints": 87.3,
    "version": "v2"
  }
}

The improvementBps field indicates how much better the RFQ fill was compared to the AMM baseline in basis points. A value of 150 means the RFQ price was 1.5% better than the best available DEX route.

Error Responses

Agent Fill

POST /api/v1/agent/rfqs/:id/fill

Agent-authenticated version of the fill endpoint. Requires the taker role. Only the agent that created the RFQ (matching wallet) can fill it.

Headers: Authorization: Bearer hq_live_...

Path Parameters

Request Body

Example

const res = await fetch(
  "https://hyperquote.xyz/api/v1/agent/rfqs/f47ac10b.../fill",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer hq_live_abc123...",
    },
    body: JSON.stringify({
      txHash: "0xabc123def456789...",
      maker: "0xAbCd1234...",
      amountIn: "1000000000",
      amountOut: "50000000000000000000",
      amountInUsd: 1000.0,
    }),
  }
);

Response (200 OK)

{
  "success": true,
  "rfqId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "txHash": "0xabc123def456789...",
  "fill": {
    "id": "clx9fill123...",
    "improvementBps": 150,
    "takerPoints": 125.5,
    "makerPoints": 87.3
  }
}

This endpoint performs three operations:

1. Marks the RFQ as FILLED in the registry and database (triggers SSE events)
2. Records the Fill and FeedFill records with points computation
3. Logs agent activity

Error Responses

Price Improvement Calculation

When an rfqId is provided, the API looks up the stored AMM baseline (captured at RFQ submission time) and computes improvement:

improvementBps = ((rfqAmountOut / baselineAmountOut) - 1) * 10000

A positive value means the RFQ fill gave the taker more output tokens than the best DEX route would have. If no baseline exists, improvementBps defaults to 0.

Related Pages

• API Overview — Endpoint index and response format
• RFQ Endpoints — Create and query RFQs
• Quote Endpoints — Submit and retrieve quotes
• Benchmark Endpoints — Baseline data and price improvement
• Error Codes — Full error reference