Search federal awards (contracts, grants, loans, direct payments) from USAspending.gov. Largest amount first within the date window. Each record includes award ID, recipient name, dollar amount, award type, awarding agency + sub-agency, start + end dates, description, and a permalink to the usaspending.gov detail page. Filter by recipient name, awarding agency name, recipient state, award type group, and date range. Backed by USAspending.gov's spending_by_award API; public-domain US government records.
/api/gov/usaspending-awardsPAYMENT-SIGNATURE.The usaspending awards API is a pay-per-call gov endpoint built for AI agents and autonomous software. Search federal awards (contracts, grants, loans, direct payments) from USAspending.gov.
There is no signup and no API key. An agent (or any HTTP client) hits the endpoint, receives an x402 "402 Payment Required" challenge, signs a sub-cent USDC payment on Base or Solana, and retries — the data comes back on the paid request. That makes it a drop-in usaspending awards data source for an agent tool-use loop, an MCP host, or a backend that needs gov data on demand without onboarding to yet another vendor portal.
| Name | Type | Description |
|---|---|---|
recipient | string | Recipient (vendor/grantee) name substring. Examples: "Microsoft", "Lockheed Martin", "Stanford University". min 2 chars · max 120 chars |
agency | string | Awarding top-tier agency name. Examples: "Department of Defense", "National Institutes of Health", "Department of Energy". min 2 chars · max 120 chars |
recipientState | string | 2-letter US state of the recipient (e.g., "CA", "VA"). min 2 chars · max 2 chars · match ^[A-Za-z]{2}$ |
awardType | string | Award type group. contracts = A/B/C/D; grants = 02/03/04/05; loans = 07/08; direct_payments = 06/10; other = 11. Default contracts. one of: contracts | grants | loans | direct_payments | other |
since | string | Earliest action date (YYYY-MM-DD). Default = 5 years ago. match ^\d{4}-\d{2}-\d{2}$ |
until | string | Latest action date (YYYY-MM-DD). Default = today. match ^\d{4}-\d{2}-\d{2}$ |
limit | integer | Records per page (1-100). Default 25. min 1 · max 100 |
page | integer | Page number (1-based). Default 1. min 1 · max 1000 |
# 1. Probe with no auth → 402 envelope with PaymentRequirements curl -sS 'https://2s.io/api/gov/usaspending-awards?recipient=xx&agency=xx&recipientState=xx&awardType=contracts&since=2024-01-01&until=2024-01-01&limit=25&page=1' # 2. Sign + retry with PAYMENT-SIGNATURE: curl -sS 'https://2s.io/api/gov/usaspending-awards?recipient=xx&agency=xx&recipientState=xx&awardType=contracts&since=2024-01-01&until=2024-01-01&limit=25&page=1' \ -H 'PAYMENT-SIGNATURE: <base64-json-payload>' # Or use the canonical runner (handles probe → sign → retry): # EVM_PRIVATE_KEY=0x... node --env-file=.env.local \ # --experimental-strip-types scripts/x402-pay.ts \ # 'https://2s.io/api/gov/usaspending-awards?recipient=xx&agency=xx&recipientState=xx&awardType=contracts&since=2024-01-01&until=2024-01-01&limit=25&page=1'
import { TwoS } from '@2sio/sdk'
const client = new TwoS({
privateKey: process.env.EVM_PRIVATE_KEY as `0x${string}`,
})
const result = await client.gov.usaspendingAwards({
"recipient": "xx",
"agency": "xx",
"recipientState": "xx",
"awardType": "contracts",
"since": "2024-01-01",
"until": "2024-01-01",
"limit": 25,
"page": 1
})
console.log('endpoint:', result.endpoint)
console.log('cost:', result.costUsd, 'USDC')
console.log('tx:', result.settlement?.txHash)
console.log('data:', result.data)import os
from twosio import TwoS
client = TwoS(private_key=os.environ["EVM_PRIVATE_KEY"])
result = client.gov.usaspending_awards(recipient="xx", agency="xx", recipientState="xx", awardType="contracts", since="2024-01-01", until="2024-01-01", limit=25, page=1)
print("endpoint:", result.endpoint)
print("cost:", result.cost_usd, "USDC")
print("tx:", (result.settlement or {}).get("tx_hash"))
print("data:", result.data)// 1. Add @2sio/mcp to your MCP host config (Claude Desktop example below).
// EVM_PRIVATE_KEY funds x402 payments per call.
// claude_desktop_config.json
{
"mcpServers": {
"2sio": {
"command": "npx",
"args": ["-y", "@2sio/mcp"],
"env": { "EVM_PRIVATE_KEY": "0x..." }
}
}
}
// 2. Once the server is running, agents call this tool via standard MCP:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "gov.usaspending-awards",
"arguments": {
"recipient": "xx",
"agency": "xx",
"recipientState": "xx",
"awardType": "contracts",
"since": "2024-01-01",
"until": "2024-01-01",
"limit": 25,
"page": 1
}
}
}| Field | Type | Description |
|---|---|---|
ok | boolean | one of: true |
items | array | |
total | integer | Total matching rows upstream; null when unknown. |
source | object | |
meta | object |
{
"ok": true,
"items": [
{
"awardId": "example",
"recipientName": "example",
"amount": 1,
"awardType": "example",
"awardingAgency": "example",
"awardingSubAgency": "example",
"startDate": "example",
"endDate": "example",
"description": "example",
"usaspendingUrl": "https://example.com"
}
],
"total": 1,
"source": {
"provider": "example",
"url": "example",
"license": "example"
},
"meta": {
"query": {
"recipient": "example",
"agency": "example",
"recipientState": "example",
"awardType": "example",
"since": "example",
"until": "example",
"limit": 1,
"page": 1
},
"hasNext": false
}
}