# ToolMint USAspending Awards

> Who won US federal money: contracts, IDVs, grants and loans from USAspending.gov as clean agent JSON — filter by keyword, recipient, agency, NAICS, state, dates, amount. Provenance + terms on every paid response.

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

## Routes

- `GET /awards` $0.01: Search federal awards by type / keyword / recipient / agency / NAICS / state / dates / amount

## Inputs

| Name | Rule |
|---|---|
| `awardType` | contracts (default), idvs, grants, loans, direct_payments, other_financial_assistance. One group per search. |
| `q` | Up to 5 comma-separated keywords, each 3-100 characters |
| `recipient` | Recipient name or UEI text, 3-100 characters |
| `agency` | Awarding top-tier agency name or abbreviation (DOE, Department of Energy). Unknown → 400, not a silent empty result. |
| `naics` | 2-6 digits; contracts and idvs only (on assistance awards it would always return nothing, so it's a 400) |
| `state` | 2-letter place-of-performance state |
| `startDate, endDate` | YYYY-MM-DD, on or after 2007-10-01. Default: the last 365 days (echoed back in query). |
| `minAmount, maxAmount` | Dollars, non-negative, up to 2 decimals |
| `sort, order` | amount (default), startDate, endDate, lastModified; desc (default) or asc. Loans have no end date. |
| `page, limit` | page is 1-based; limit 1-100 (default 10); page × limit ≤ 10,000 |

## What you get

- awards[]: awardId, internalId, recipientName, recipientUei, amount, amountKind (obligated | loan_value), totalOutlays, subsidyCost (loans)
- description (≤ 500 chars), startDate, endDate, lastModified, awardingAgency, awardingSubAgency, awardType
- naics {code, description}, psc {code, description}, assistanceListings [{number, title}], placeOfPerformanceState, uiUrl
- Fields that don't apply to a group are null, so every award has the same shape.
- query (normalized, with the resolved agency name), page {page, limit, hasNext}, provenance (sourceUrl, fetchedAt, requestHash, contentHash), terms, notice, cacheHit (10 min)

## Sources and terms

- USAspending.gov API v2 (US Treasury, Bureau of the Fiscal Service), POST /search/spending_by_award/ and the toptier agency list (cached 24 h). Free, public, no key. US government data.
- api.usaspending.gov has no robots.txt (404). One upstream call per search; product User-Agent with contact address.

## Limits (read before relying on it)

- Amounts are what agencies report under the DATA Act and can be revised. Verify on uiUrl before relying on a figure.
- Not an official Treasury or GSA product.
- Wide searches can be slow upstream; a timeout returns 502 and is not charged.

## Example

```
GET /awards?awardType=contracts&q=cybersecurity&state=TX&limit=10
```