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

# Freight Rate Quote

> Quote a freight lane between two US ZIP codes for a pickup date, by mode.

Quote the rate to move freight between two US ZIP codes on a pickup date, by mode: ltl shares a trailer by the pallet, ftl is a whole 53-foot dry van, van is a cargo van and box\_truck is a 26-foot box truck. The answer is one carrier's quote for that lane: the rate for the whole shipment with every included service, the transit time, the pickup and delivery dates, when the quote lapses and whether it is firm or indicative. Use it to check a billed freight charge against the lane's going rate. For ltl give the pallets, the weight per pallet and the pallet dimensions; for van and box\_truck give the pallets and the weight per pallet; for ftl the lane and date are enough. A lane the mode does not serve is refused as invalid input: try another mode. Covers US lanes. Nothing is booked.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

<ParamField body="origin_zip" type="string" required>
  Where the freight is collected. 5-digit US ZIP code.
</ParamField>

<ParamField body="destination_zip" type="string" required>
  Where the freight is delivered. 5-digit US ZIP code.
</ParamField>

<ParamField body="mode" type="string" required>
  How the freight moves. Picks the quote asked for; there is no default. One of `ltl`, `ftl`, `van`, `box_truck`.
</ParamField>

<ParamField body="pickup_date" type="string" required>
  The day the freight is collected: today (UTC) or later. YYYY-MM-DD.
</ParamField>

<ParamField body="pallets" type="integer">
  How many pallets. Required for ltl, van (up to 3) and box\_truck (up to 12); not needed for ftl. At least 1.
</ParamField>

<ParamField body="weight_lbs_per_pallet" type="integer">
  The weight of each pallet in pounds. Required for ltl, van (3,500 lb in all) and box\_truck (10,000 lb in all); not needed for ftl. At least 1.
</ParamField>

<ParamField body="length_in" type="integer">
  The length of each pallet in inches. Required for ltl; ignored for other modes. At least 1.
</ParamField>

<ParamField body="width_in" type="integer">
  The width of each pallet in inches. Required for ltl; ignored for other modes. At least 1.
</ParamField>

<ParamField body="height_in" type="integer">
  The height of each pallet in inches, up to 85. Required for ltl; ignored for other modes. At least 1.
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

<ResponseField name="data.request_id" type="string">
  Durable job ID for audit and lookup
</ResponseField>

<ResponseField name="data.status" type="string">
  Job status: `completed`
</ResponseField>

<ResponseField name="data.tool" type="string">
  Always `market_freight_rate`
</ResponseField>

<ResponseField name="data.result" type="object">
  The answer, described under Result below
</ResponseField>

<ResponseField name="data.evidence" type="object">
  Where the answer came from and when
</ResponseField>

<ResponseField name="data.evidence.source" type="string">
  `null`. The data comes from a commercial source.
</ResponseField>

<ResponseField name="data.evidence.source_kind" type="string">
  `public` when the data comes from a public body, `commercial` otherwise
</ResponseField>

<ResponseField name="data.evidence.retrieved_at" type="string">
  When the lookup was made, as an ISO 8601 UTC time
</ResponseField>

<ResponseField name="data.evidence.as_of" type="string">
  When the source says the fact was last updated, or `null` when the source gives no date
</ResponseField>

## Result

Nested under `data.result`.

<ResponseField name="data.result.rate" type="number">
  The quoted price for the whole shipment, every included service counted.
</ResponseField>

<ResponseField name="data.result.currency" type="string">
  The currency of the rate, as an ISO 4217 code.
</ResponseField>

<ResponseField name="data.result.mode" type="string">
  The mode quoted. Differs from the mode asked for when no shared-trailer service covers the lane and a whole truck was quoted instead.
</ResponseField>

<ResponseField name="data.result.transit_days" type="integer">
  Days from pickup to delivery.
</ResponseField>

<ResponseField name="data.result.pickup_date" type="string">
  YYYY-MM-DD.
</ResponseField>

<ResponseField name="data.result.delivery_date" type="string">
  YYYY-MM-DD.
</ResponseField>

<ResponseField name="data.result.valid_until" type="string">
  When the quote lapses, ISO 8601.
</ResponseField>

<ResponseField name="data.result.quote_tier" type="string">
  firm: every pricing input was given, so the price stands as quoted. indicative: an optional detail such as the commodity was not given, so the price can change at booking.
</ResponseField>

<ResponseField name="data.result.included_services" type="string[]">
  Services the rate already covers, such as liftgate or residential delivery.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/lookup/market-freight-rate \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "origin_zip": "90012",
      "destination_zip": "94105",
      "mode": "ltl",
      "pickup_date": "2026-10-20",
      "pallets": 2,
      "weight_lbs_per_pallet": 800,
      "length_in": 48,
      "width_in": 40,
      "height_in": 48
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/market-freight-rate", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      "origin_zip": "90012",
      "destination_zip": "94105",
      "mode": "ltl",
      "pickup_date": "2026-10-20",
      "pallets": 2,
      "weight_lbs_per_pallet": 800,
      "length_in": 48,
      "width_in": 40,
      "height_in": 48
    }),
  });
  ```

  ```typescript SDK theme={null}
  const result = await agent.tool('lookup/market-freight-rate', {
    origin_zip: '90012',
    destination_zip: '94105',
    mode: 'ltl',
    pickup_date: '2026-10-20',
    pallets: 2,
    weight_lbs_per_pallet: 800,
    length_in: 48,
    width_in: 40,
    height_in: 48
  });
  console.log(result.data.result);
  console.log(result.data.evidence);
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200) theme={null}
  {
    "success": true,
    "data": {
      "request_id": "uuid",
      "receipt_id": "rcpt_...",
      "status": "completed",
      "tool": "market_freight_rate",
      "result": {
        "rate": 329.95,
        "currency": "USD",
        "mode": "ltl",
        "transit_days": 3,
        "pickup_date": "2026-10-20",
        "delivery_date": "2026-10-23",
        "valid_until": "2026-10-18T03:36:09.269Z",
        "quote_tier": "indicative",
        "included_services": [
          "liftgate",
          "residential delivery",
          "delivery appointment",
          "limited access",
          "notify before delivery"
        ]
      },
      "evidence": {
        "source": null,
        "source_kind": "commercial",
        "retrieved_at": "2026-10-14T03:36:09.269Z",
        "calls": [
          {
            "retrieved_at": "2026-10-14T03:36:09.269Z"
          }
        ],
        "as_of": null
      }
    }
  }
  ```
</ResponseExample>

<Info>See [Pricing](/pricing) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.</Info>

## Notes

* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.