job.federal-codes

Fetch a USAJobs reference codelist (lookup tables behind every federal job posting). Pass name to pick which list: agencysubelements (every agency + sub-element), occupationalseries (2210 IT, 0301 Misc Admin, 0801 Engineer, etc.), paygrades, payplans (GS, SES, ES, WG, etc.), hiringpaths (veteran, military spouse, native American, etc.), securityclearances, locationcodes, countries, countrysubdivisions, ethnicities, racecodes, militarystatuscodes, languagecodes, positionscheduletypecodes (full-time/part-time/seasonal), travelpercentages, missioncriticalcodes, cyberworkroles, etc. (33 lists total). Use the returned codes as filter inputs to /api/job/federal-search.

price
$0.0012 USDC per call
method
GET/api/job/federal-codes
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

NameTypeDescription
namerequiredstring
one of: academichonors | agencysubelements | announcementclosingtypes | applicantsuppliers | cyberworkroles | countries | countrysubdivisions | degreetypecodes | documentations | ethnicities | federalemploymentstatuses | geoloccodes | hiringpaths | languagecodes | languageproficiencies | locationcodes | militarystatuscodes | missioncriticalcodes | occupationalseries | paygrades | payplans | positionofferingtypecodes | positionopeningstatuses | positionscheduletypecodes | racecodes | refereetypecodes | remunerationrateintervalcodes | requiredstandarddocuments | securityclearances | servicetypes | specialhirings | travelpercentages | whomayapply

Code samples

cURLbash
# 1. Probe with no auth → 402 envelope with PaymentRequirements
curl -sS 'https://2s.io/api/job/federal-codes?name=academichonors'

# 2. Sign + retry with PAYMENT-SIGNATURE:
curl -sS 'https://2s.io/api/job/federal-codes?name=academichonors' \
  -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/job/federal-codes?name=academichonors'
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.job.federalCodes({
  "name": "academichonors"
})

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.job.federal_codes(name="academichonors")

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": "job.federal-codes",
    "arguments": {
      "name": "academichonors"
    }
  }
}

Discovery

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.