# USAspending on Onekey

> 8 endpoints for USAspending (8 stable, 0 beta), 1 to 5 credits each. Category: Government & public data. One key, one JSON shape.

Base URL: https://api.onekey.dev
Auth: header `x-api-key: <key>`. Call shape: `GET /v1/{platform}/{endpoint}?{params}`.
Every response is `{success, data, metadata, error}`; check `success` first. Cost is in `metadata.credits_charged`. Free when served from cache (0.2 credit for a cached response over 100 KB). Failed and not-found calls are refunded.
Status: stable = verified against the live source; beta = not yet verified, fields may be missing.

Page: https://onekey.dev/platforms/usaspending
Reference (Markdown): https://onekey.dev/docs/api/usaspending.md
All docs: https://onekey.dev/llms.txt

## Canonical fields returned

Unified-schema fields (same names on every platform), with how many of the 8 mapped USAspending endpoints return each:

- `entity.id` (string): 8
- `entity.name` (string): 7
- `entity.description` (string): 3
- `entity.category` (string): 2
- `entity.createdAt` (ISO 8601 date): 1
- `entity.date` (ISO 8601 date): 1
- `entity.url` (URL): 1
- plus 11 platform-specific fields under `ext.`

## Endpoints

### usaspending.agencies

Top-tier federal agencies with budget authority and obligations.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/usaspending/agencies` with header `x-api-key: YOUR_API_KEY`
- Parameters: none
- Fields returned: `entity.id`, `entity.name`, `ext.symbol`, `ext.budgetAuthority`, `ext.obligated`, `ext.outlays`, `ext.budgetSharePct`, `ext.fiscalYear`
- Reference: https://onekey.dev/docs/api/usaspending/agencies.md

### usaspending.agency

One federal agency profile by toptier code (e.g. 012 = USDA).
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/usaspending/agency?code=012` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `code` (string, required): Toptier agency code (3-4 digits)
- Fields returned: `entity.id`, `entity.name`, `entity.description`, `entity.url`, `ext.symbol`, `ext.fiscalYear`, `ext.subtierAgencies`
- Reference: https://onekey.dev/docs/api/usaspending/agency.md

### usaspending.award_search

Search federal contract awards by keyword and calendar year.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/usaspending/award_search?q=software` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Keyword
  - `year` (string, optional, default 2024): Calendar year
- Fields returned: `entity.id`, `entity.name`, `entity.description`, `entity.category`, `entity.createdAt`, `entity.date`, `ext.amount`
- Reference: https://onekey.dev/docs/api/usaspending/award_search.md

### usaspending.budgetary_resources

Total budgetary resources by fiscal year and period.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/usaspending/budgetary_resources` with header `x-api-key: YOUR_API_KEY`
- Parameters: none
- Fields returned: `entity.id`, `ext.fiscalPeriod`, `ext.totalBudgetaryResources`
- Reference: https://onekey.dev/docs/api/usaspending/budgetary_resources.md

### usaspending.glossary

USAspending glossary terms (paged).
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/usaspending/glossary?limit=5` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `limit` (string, optional, default 20): Rows (1-100)
- Fields returned: `entity.id`, `entity.name`, `entity.description`
- Reference: https://onekey.dev/docs/api/usaspending/glossary.md

### usaspending.naics

NAICS industry codes matching a filter.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/usaspending/naics?q=software` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Filter text or code
- Fields returned: `entity.id`, `entity.name`, `ext.count`
- Reference: https://onekey.dev/docs/api/usaspending/naics.md

### usaspending.recipient_autocomplete

Autocomplete federal award recipients by name.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/usaspending/recipient_autocomplete?q=apple` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Recipient name fragment
- Fields returned: `entity.name`, `entity.id`, `entity.category`
- Reference: https://onekey.dev/docs/api/usaspending/recipient_autocomplete.md

### usaspending.spending_by_state

Federal award spending by US state (recipient location).
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/usaspending/spending_by_state` with header `x-api-key: YOUR_API_KEY`
- Parameters: none
- Fields returned: `entity.id`, `entity.name`, `ext.amount`, `ext.count`
- Reference: https://onekey.dev/docs/api/usaspending/spending_by_state.md

## Sample request

```bash
curl "https://api.onekey.dev/v1/usaspending/agency?code=012" \
  -H "x-api-key: YOUR_API_KEY"
```