# ToolMint SAM.gov Opportunities

> US federal contract opportunities from SAM.gov as clean agent JSON — filter by keyword, NAICS, state, posted dates. Provenance + terms on every paid response.

- Status: Coming soon
- Price: $0.02 / call (x402 exact, USDC on Base eip155:8453, payTo 0xfbF7413bcB3a604936775C96FDbe0b0C9c9E37F5)
- Planned URL: https://toolmint-sam-gov-opportunities.toolmint.workers.dev
- OpenAPI: https://toolmint.toolmint.workers.dev/tools/sam-gov-opportunities-json/openapi.json

## Routes

- `GET /opportunities` $0.02: Search opportunities by keyword / NAICS / state / posted dates

## What question it answers

"Which US federal contract opportunities on SAM.gov match this keyword, NAICS code, state and posting window?" You get a page of up to 100 notices as normalized JSON, with the notice link, dates, agency and a content hash of what SAM.gov returned.

## When to use it

- A government-contracting agent needs open solicitations by keyword, NAICS code or state.
- You want one stable JSON shape, plus provenance, instead of parsing SAM.gov yourself.

## When not to

- Not an official GSA product, and not a legal source. Open the notice (`uiUrl`) and verify before bidding.
- By default the tool uses SAM.gov's public website search, which is not GSA's official API. The `naics`, `state` and date filters are best-effort on that path.
- It does not fetch attachments, award history or entity registrations. Descriptions are cut to 500 characters.

## Example

```bash
curl -i "https://toolmint-sam-gov-opportunities.toolmint.workers.dev/opportunities?q=software&naics=541511&state=TX&limit=10"
```
Without payment this returns HTTP 402. Trimmed 200 response shape (the notice values are the sample in the Worker's own discovery metadata, not a fresh pull):
```json
{
  "tool": "sam-gov-opportunities-json",
  "version": "0.1.0",
  "query": { "q": "software", "naics": "541511", "state": "TX", "postedFrom": null, "postedTo": null,
             "page": 0, "limit": 10, "activeOnly": true, "transport": "public_hal" },
  "totalElements": 2475,
  "count": 1,
  "opportunities": [{
    "id": "f2413ed545264d0baf1785bbaea33e61",
    "title": "7A21--CVI 42 Evolve Tier 1 License Subscription",
    "solicitationNumber": "36C24527Q0045",
    "noticeType": "Combined Synopsis/Solicitation",
    "noticeTypeCode": "k",
    "publishDate": "2026-10-29T19:27:11+00:00",
    "responseDate": "2026-11-05T17:00:00+00:00",
    "isActive": true, "isCanceled": false,
    "department": "VETERANS AFFAIRS, DEPARTMENT OF",
    "organization": "245-NETWORK CONTRACT OFFICE 5 (36C245)",
    "descriptionExcerpt": "CVI Evolve Software, Support and Service ...",
    "naics": null,
    "uiUrl": "https://sam.gov/opp/f2413ed545264d0baf1785bbaea33e61/view"
  }],
  "provenance": { "sourceUrl": "https://sam.gov/api/prod/sgs/v1/search/", "fetchedAt": "2026-10-31T...Z",
                  "toolVersion": "0.1.0", "transport": "public_hal", "contentHash": "sha256:..." },
  "terms": { "source": "SAM.gov public opportunities (US federal)", "...": "..." },
  "notice": "naics/state/postedFrom/postedTo are best-effort filters on the public search; verify on the notice page (uiUrl) before bidding.",
  "cacheHit": false,
  "paymentMeta": { "x402": true, "scheme": "exact", "price": "$0.02", "asset": "USDC", "network": "eip155:8453" }
}
```

Parameters: `q` (up to 200 chars), `naics` (2 to 6 digits), `state` (2 letters), `postedFrom` / `postedTo` (`YYYY-MM-DD`), `page` (0-based), `limit` (1 to 100, default 10), `activeOnly` (default true). `useOfficialApi=true` works only if the operator has set a SAM key on the Worker; otherwise it is a 400.

## Data source and licence

SAM.gov opportunity data (US federal public procurement data), via SAM.gov's public search, or via the official GSA Get Opportunities API when the operator configures a key. Use is subject to SAM.gov and GSA policies; check the source's terms for your use. ToolMint adds no data of its own.

## Freshness and limits

- Cached 10 minutes per identical query on a warm Worker instance; a cached answer keeps the original `fetchedAt`.
- At most 100 results per call; paging stays within the first 10,000 records.
- 20 second upstream timeout, 5 MB response cap.
- The public search endpoint is not GSA's official API and may change or rate-limit without notice; a failure is a 502, not charged.