BidDelta — SAM.gov material change watchlist

BidDelta tells you what changed in a federal contract opportunity you already care about. It watches narrow searches or known notices through the official SAM.gov Contract Opportunities Public API and produces source-linked alerts when pursuit-relevant fields change.

This release is a limited free-beta candidate. There is no BidDelta fee during the beta; users pay only the normal Apify platform usage consumed by their own runs. The beta exists to prove reliability and usefulness before any future monetization decision.

What BidDelta watches

• response deadlines;
• official active status;
• set-aside code and description;
• notice type and solicitation number;
• NAICS and classification codes;
• place of performance and point of contact;
• award metadata;
• official description and attachment-link metadata;
• new opportunities matching a configured search.

Each result includes before-and-after values, a review priority, why the change may matter, a deterministic event ID, matching search IDs, an official notice link, source attribution, retrieval time, and explicit coverage boundaries.

BidDelta does not make a bid/no-bid decision. Always verify the current official notice before changing a pursuit or submission plan.

Try it without a SAM.gov key

Fixture mode makes no network request. Use the prepared examples/fixture-demo-input.json, or keep:

{
  "monitorId": "fixture-demo",
  "dryRun": true,
  "sourceMode": "fixture",
  "emitBaseline": true,
  "searches": [
    {
      "id": "example-hvac",
      "lookbackDays": 90,
      "naicsCode": "238220",
      "limit": 100
    }
  ]
}

The fixture demonstration emits a clearly synthetic example. For a real monitor, keep emitBaseline=false; the first successful run then establishes a free baseline rather than reporting existing notices as changes.

Run against official SAM.gov data

Live source mode requires your own SAM.gov public API key. Enter it in the masked SAM.gov public API key field. Apify encrypts secret inputs before storing them and decrypts them only inside the Actor run.

Private deployments may alternatively provide the secret environment variable SAM_GOV_API_KEY. Never place a key in an ordinary field, source code, logs, datasets, or a shared URL.

Start with a deliberately narrow dry run:

{
  "monitorId": "my-bid-watch",
  "dryRun": true,
  "sourceMode": "sam-api",
  "emitBaseline": false,
  "searches": [
    {
      "id": "hvac-alabama",
      "lookbackDays": 7,
      "naicsCode": "238220",
      "state": "AL",
      "limit": 10
    }
  ],
  "maxPagesPerSearch": 1,
  "missingThreshold": 2
}

For unattended monitoring, use lookbackDays; BidDelta recalculates the date window on every run. For a known older opportunity, use an exact noticeId or solicitationNumber with fixed postedFrom and postedTo dates.

Safety and coverage boundaries

• Uses the official SAM.gov public API and supported user credentials.
• Never bypasses source access controls.
• Strips query strings before persisting source links, reducing API-key leak risk.
• Treats attachments as metadata only; it never downloads or redistributes attachment content.
• Fails without advancing monitor state when a result set is truncated.
• Requires repeated successful misses before reporting a missing-record signal.
• Never labels absence alone as a cancellation.
• Compares BidDelta's stored snapshots because the public API returns the latest active version, not complete source version history.
• Requires official-source verification before a real pursuit decision.

BidDelta is maintained independently and is not affiliated with or endorsed by SAM.gov or the U.S. General Services Administration.

Output and duplicate handling

Dataset delivery is at-least-once. Every material event has a deterministic eventId, so downstream systems can suppress duplicate projections.

During the free beta, keep dryRun=true; no custom Pay-Per-Event charge is attempted. The future billing path:

1. saves the event to a durable outbox;
2. confirms the run budget before exposing a paid result;
3. records the current run's authoritative charged-event count;
4. projects the customer-visible result;
5. saves a charge intent and deterministic idempotency key;
6. performs bounded same-key retries, including safe same-run restart recovery;
7. reconciles a prior terminal run before any cross-run retry;
8. stops later billing whenever the authoritative count is unavailable or inconsistent.

Under the single-monitor, non-overlapping-run boundary, a later run retries only when the prior terminal run proves no charge was accepted. Strict global exactly-once billing is not claimed when that boundary is violated or the authoritative run record cannot be read.

Recommended beta operation

• 128 MB memory;
• one narrow monitor per stable monitorId;
• dryRun=true;
• no overlapping runs for the same monitor;
• no schedule until two reviewed API-mode runs succeed;
• daily or hourly checks only after measuring real source freshness and cost.

Feedback that matters

Open the Actor's Issues tab, include the event's eventId, and answer:

1. What worked?
2. What was confusing or wrong?
3. Did this alert change or protect an action?

The beta measures unique and repeat users, source-verified material changes, false alerts, source failures, retained monitors, run cost, and support time. Raw run count alone is not proof of demand.

Local verification

npm ci
npm test
npm run check
npx apify-cli validate-schema

The automated suite covers normalization, baseline behavior, material deltas, missing-record semantics, source-identity resets, pagination, truncation, credential sanitization, budget refusal, durable outbox ordering, same-run idempotent charge retry, terminal-run charge reconciliation, proof-based cross-run retry, and fail-closed billing uncertainty.

Documentation

• docs/PRODUCT_REVERSE_SPEC.md
• docs/STATE_AND_BILLING_PROTOCOL.md
• docs/LIVE_VALIDATION_RUNBOOK.md
• docs/PRIVATE_PILOT.md
• docs/FREE_BETA_RELEASE.md
• docs/BETA_METRICS.md
• docs/COST_AND_PRICING_MODEL.md
• docs/PUBLISHING_DRAFT.md
• docs/VERIFICATION_REPORT.md