gov.usaspending-awards

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.

price

$0.0024 USDC per call

method

GET/api/gov/usaspending-awards

payment

x402 v2 · USDC on Base (EIP-3009) or Solana (SPL transfer)

auth

None. Sign the payment, retry with PAYMENT-SIGNATURE.

tier

Tier 0 — no paid upstream

Parameters

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

Code samples

cURLbash

# 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'

TypeScript / Node — @2sio/sdktypescript

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)

Python — 2siopython

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)

MCP — Claude Desktop / AgentKit / any MCP hostjson

// 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
    }
  }
}

Response

Field	Type	Description
`query`	object
`returned`	integer
`hasNext`	boolean
`awards`	array
`source`	object

Example response datajson

{
  "query": {
    "recipient": "example",
    "agency": "example",
    "recipientState": "example",
    "awardType": "example",
    "since": "example",
    "until": "example",
    "limit": 1,
    "page": 1
  },
  "returned": 1,
  "hasNext": false,
  "awards": [
    {
      "awardId": "example",
      "recipientName": "example",
      "amount": 1,
      "awardType": "example",
      "awardingAgency": "example",
      "awardingSubAgency": "example",
      "startDate": "example",
      "endDate": "example",
      "description": "example",
      "usaspendingUrl": "https://example.com"
    }
  ],
  "source": {
    "provider": "example",
    "url": "https://example.com",
    "license": "example"
  }
}

Discovery

/api/directory — full catalog of every endpoint
/openapi.json — OpenAPI 3.1 spec (per-op x-payment-info, x402Payment security)
/.well-known/x402 — machine-readable service descriptor for x402-aware crawlers
/.well-known/mcp/server-card.json — MCP SEP-1649 server card
/llms.txt — plain-text manifest for LLM ingestion

2s.io is x402-native. Every call is paid per-request from a USDC-funded EVM wallet on Base — no signup, no API keys, no monthly fees. Source code: github.com/2s-io/sdk.