# govlaws.ai

U.S. federal regulation and U.S. Code data for AI agents. Instant citation lookup, semantic search, change detection, and a programmable control plane over official government sources (eCFR + Federal Register + OLRC U.S. Code canary coverage).

## What this is

govlaws.ai is a REST API that gives AI agents structured access to U.S. federal regulations and canary U.S. Code sections. Instead of scraping .gov websites, agents call our API to get current federal legal text with provenance metadata anchored to official government sources. The current V1 surface adds usage tracking, budget controls, webhook subscriptions, and key rotation for agent-managed accounts.

## Quick start (3 calls)

### 1. Start signup (returns Stripe checkout URL)
```
curl -X POST https://govlaws.ai/api/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "your-agent@yourcompany.ai", "plan": "free"}'
```
Response includes a `checkout_url`. Complete checkout (free tier collects a payment method but does not charge). Then poll `GET /api/signup/status?session_id={session_id}` to retrieve your API key.

### 2. Resolve a citation
```
curl "https://govlaws.ai/api/resolve?citation=12+CFR+1026.43" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
U.S. Code canary example: `GET /api/resolve?citation=15+U.S.C.+§+1681`

### 3. Search federal legal text
```
curl -X POST https://govlaws.ai/api/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mortgage underwriting qualified mortgage standards", "limit": 5}'
```
The default search corpus is `regulations` for backward compatibility. Use `{"corpus":"statutes"}` for U.S. Code canary search or `{"corpus":"all"}` for CFR plus U.S. Code.

## Authentication

API-key endpoints require:
- Header: `Authorization: Bearer glaw_sk_live_...`
- Or: `X-API-Key: glaw_sk_live_...`

MPP endpoints under `/api/mpp/*` do not require an API key; they use `402 Payment Required` challenges and payment proof instead.

## MCP server

GovLaws also exposes a read-only remote MCP server for agent installs:
- Endpoint: `https://govlaws.ai/mcp`
- Auth: `Authorization: Bearer glaw_sk_live_...`
- Tools: `resolve`, `search`, `changes`

Use MCP when your agent client supports direct remote tool installation. Use the REST API when you are building a direct integration, and use MPP when you want no-account pay-per-request access.

## Core Endpoints

### POST /api/signup
Create account via Stripe checkout. No form, no approval queue.
- Body: `{"email": "...", "plan": "free|developer|pro"}`
- Returns: checkout_url, session_id, plan, requests_limit
- After checkout: `GET /api/signup/status?session_id={id}` returns api_key (shown once)

### GET /api/resolve?citation={citation}
Resolve a CFR or U.S. Code citation to current text + provenance.
- Examples: `?citation=12+CFR+1026.43`, `?citation=15+U.S.C.+§+1681`
- Returns: title, text, source URL, freshness timestamp, recent changes, provenance object

### POST /api/search
Semantic search over federal regulations and U.S. Code canary coverage.
- Body: `{"query": "...", "limit": 5, "corpus": "regulations|statutes|all"}`
- Default corpus: `regulations`
- Returns: ranked results with citation, title, relevance score, snippet

### GET /api/changes
Recent regulatory changes from the Federal Register.
- Params: `?agency=CFPB&days=30` or `?citation=12+CFR+1026`
- Returns: list of change events with effective_date, document_number, FR URL

### GET /api/status
System health and data freshness (no auth required).
- Returns: healthy/degraded status, last_sync timestamps per source

## V1 Endpoints

### GET /api/usage
Current plan, request counts, billing period, and budget status.
- Returns: plan, requests_used, requests_limit, period, budget (if configured)
```
curl https://govlaws.ai/api/usage \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /api/budgets
Retrieve current budget configuration.
- Returns: budget object with caps, current spend, status

### POST /api/budgets
Set or update spend controls. Requires Pro plan. Writes an audit event on every change.
- Body: `{"soft_cap_usd": 150, "hard_cap_usd": 200, "notify_webhook_url": "https://your-agent.ai/webhooks/budget"}`
- Returns: budget object with updated values
```
curl -X POST https://govlaws.ai/api/budgets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"soft_cap_usd": 150, "hard_cap_usd": 200}'
```

### GET /api/subscribe
List your active webhook subscriptions. Requires Pro plan.
- Returns: array of subscriptions with id, citation_pattern, webhook_url, status

### POST /api/subscribe
Register a webhook to receive change notifications. Requires Pro plan. Max 50 active subscriptions.
- Body: `{"citation_pattern": "12 CFR 1026.*", "webhook_url": "https://...", "webhook_secret": "whsec_...", "filters": {"change_types": ["amendment", "final_rule"]}}`
- Returns: subscription_id, status
- Payloads are signed with HMAC-SHA256 via `X-Govlaws-Signature` header
- Retries with exponential backoff: 1m, 5m, 30m, 2h, 24h
```
curl -X POST https://govlaws.ai/api/subscribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"citation_pattern": "12 CFR 1026.*", "webhook_url": "https://your-agent.ai/webhooks/govlaws", "webhook_secret": "whsec_your_secret_here"}'
```

### DELETE /api/subscribe?id={subscription_id}
Deactivate a webhook subscription.
- Returns: subscription_id, status: "deactivated"

### POST /api/keys/rotate
Rotate a key: deactivates the old key and issues a new one with the same name.
- Body: `{"id": "key_id_to_rotate"}`
- Returns: new plaintext api_key (shown ONCE), old key info

## Rate limits

| Plan      | Price         | Requests/month |
|-----------|---------------|----------------|
| free      | $0            | 10             |
| developer | $49/mo        | 5,000          |
| pro       | $499/mo       | 100,000        |

Rate limit headers returned on every response:
- `X-RateLimit-Limit` — monthly limit
- `X-RateLimit-Remaining` — requests left this month
- `X-RateLimit-Reset` — ISO 8601 timestamp when limit resets

429 responses include `upgrade_url` and `reset_at` fields.

## Plan-gated features

| Feature        | Free | Developer | Pro |
|----------------|------|-----------|-----|
| resolve        | ✓    | ✓         | ✓   |
| search         | ✓    | ✓         | ✓   |
| changes        | ✓    | ✓         | ✓   |
| budget controls|      |           | ✓   |
| webhooks       |      |           | ✓   |
| key rotation   |      |           | ✓   |

## Data sources

- **eCFR** (ecfr.gov) — current federal regulations, updated every 4 hours
- **Federal Register** (federalregister.gov) — regulatory changes and notices, updated every 4 hours
- **Office of the Law Revision Counsel U.S. Code** (uscode.house.gov) — current U.S. Code canary sections from USLM XML, weekly canary freshness policy
- **GovInfo** (govinfo.gov) — official artifact URLs for provenance anchoring

Note: eCFR is not an official legal edition of the CFR. U.S. Code positive-law title status is reported in provenance when known. All responses include provenance metadata. Section-level GovInfo CFR PDF/detail URLs and OLRC U.S. Code XML package URLs are promoted into `official_artifact_url` when available; title-level bulk XML remains source metadata only.

## Provenance

`/api/resolve`, `/api/batch-resolve`, and each `/api/changes` item carry a `provenance` object. `/api/search` carries a top-level `provenance` block for the searched corpus.

Agents should branch on `trust.disclaimer_code` and `trust.citation_suitability` rather than parsing the prose `disclaimer`.

```json
{
  "provenance": {
    "is_official_edition": false,
    "disclaimer": "Derived from the eCFR, which is not an official legal edition of the CFR.",
    "official_artifact_url": null,
    "govinfo_source_url": "https://www.govinfo.gov/bulkdata/ECFR/title-12/ECFR-title12.xml",
    "ecfr_url": "https://www.ecfr.gov/current/title-12/section-1026.43",
    "source_system": "ecfr",
    "currency": {
      "reflects_current_text": true,
      "as_of": "2026-04-16T08:00:00Z",
      "effective_date": null
    },
    "official_edition": { "is_official": false, "edition_year": null, "artifact_url": null },
    "trust": {
      "disclaimer_code": "ECFR_UNOFFICIAL",
      "citation_suitability": ["research", "reference"]
    }
  }
}
```

Disclaimer codes:
- `ECFR_UNOFFICIAL` — current eCFR text (reflects latest regulatory state, but not an official legal edition). Suitability: research, reference.
- `FR_NOTICE` — Federal Register notice (official publication of record). Suitability: research, reference, legal_filing.
- `GOVINFO_OFFICIAL` — GovInfo annual CFR (official legal edition; may lag current state by up to a year). Suitability: research, reference, legal_filing.
- `USCODE_CURRENT` — current U.S. Code text from OLRC XML through the stated public law release point. Suitability: research, reference unless positive-law/official suitability is explicitly shown.

## Pay-per-request via MPP (no signup required)

GovLaws supports the Machine Payments Protocol (MPP) for agent-native access. No API key, no account, no checkout — just pay per request. Tempo pathUSD is the primary micro-payment rail. Stripe Machine Payments is configured for higher-value MPP charges that meet Stripe minimums, such as future bundles and agent packs.

MPP docs: https://govlaws.ai/mpp
Stripe Machine Payments profile: `profile_61UaOKlpBFHxP0R5pA6UaOKk7KSQvQPU9rJGTEP6GNCq`

### How it works

1. Request a paid endpoint without credentials
2. Receive a `402 Payment Required` response with one or more payment challenges
3. Pay the challenge (your MPP client handles this automatically)
4. Retry with payment proof — receive data + payment receipt

### MPP endpoints

#### Resolve a citation ($0.05)
```
GET https://govlaws.ai/api/mpp/resolve?citation=12+CFR+1026.43
```
U.S. Code canary example:
```
GET https://govlaws.ai/api/mpp/resolve?citation=15+U.S.C.+§+1681
```

#### Batch resolve citations ($0.15, up to 10 citations)
```
POST https://govlaws.ai/api/mpp/batch-resolve
Content-Type: application/json
{"citations": ["12 CFR 1026.43", "15 U.S.C. § 1681"], "fields": ["citation", "title", "text", "provenance"]}
```

#### Search federal legal text ($0.03)
```
POST https://govlaws.ai/api/mpp/search
Content-Type: application/json
{"query": "mortgage underwriting qualified mortgage standards", "limit": 5}
```
U.S. Code canary search:
```
POST https://govlaws.ai/api/mpp/search
Content-Type: application/json
{"query": "fair credit reporting congressional findings", "limit": 5, "corpus": "statutes"}
```

#### Recent changes ($0.03)
```
GET https://govlaws.ai/api/mpp/changes?agency=CFPB&days=30
```

#### Re-authenticate with zero-dollar MPP auth
```
GET https://govlaws.ai/api/mpp/identity
```
Returns the verified payer identity plus prior MPP payment and refund state. Use this after a paid request when you need to prove you are the same agent without paying again.

#### Request or inspect refunds
```
GET https://govlaws.ai/api/mpp/refunds
POST https://govlaws.ai/api/mpp/refunds
Content-Type: application/json
{"receipt_id": "rcpt_...", "reason": "upstream processing failed"}
```
Refund requests are authenticated with zero-dollar MPP auth and always tied back to the original payer identity.

### Quick test with mppx CLI
```bash
npx mppx account create
npx mppx https://govlaws.ai/api/mpp/resolve?citation=12+CFR+1026.43
```

### Agent prompts

- "Resolve 12 CFR 1026.43 using GovLaws via MPP"
- "Resolve 15 U.S.C. § 1681 using GovLaws via MPP"
- "Search current CFPB mortgage servicing regulations using GovLaws"
- "Search U.S. Code statutes about fair credit reporting using GovLaws"
- "Check recent changes to 12 CFR 1026 using GovLaws"

MPP responses include the same provenance, freshness, and source metadata as the API-key endpoints. Preferred payment method for current $0.03-$0.15 calls: Tempo pathUSD stablecoin. Stripe Machine Payments is reserved for eligible higher-value MPP charges and is currently priced by Stripe at 1.5% per successful charge, rounded to the nearest cent.

## Pay-per-request via x402 (AgentCore / Bazaar-compatible)

GovLaws also exposes a separate x402 lane for agents that discover and pay through Coinbase x402 Bazaar, Amazon Bedrock AgentCore Payments, or other x402-compatible clients. This lane uses exact USDC payments on Base through the Coinbase CDP Facilitator and returns the same legal response shapes as REST and MPP.

This lane is separate from MPP/Tempo. `/api/mpp/*` uses Tempo pathUSD and `MPP_TEMPO_RECIPIENT`; `/api/x402/*` uses Base USDC and the explicitly configured `X402_PAY_TO_ADDRESS`. GovLaws does not fall back from x402 to the Tempo recipient.

x402 endpoints:
- `GET https://govlaws.ai/api/x402/resolve?citation=12+CFR+1026.43` — `$0.05`
- `POST https://govlaws.ai/api/x402/search` — `$0.03`
- `GET https://govlaws.ai/api/x402/changes?agency=CFPB&days=30` — `$0.03`

Payment metadata:
- scheme: `exact`
- network: `eip155:8453`
- currency: Base USDC
- facilitator: `https://api.cdp.coinbase.com/platform/v2/x402`

Use MPP/Tempo for existing MPP clients. Use `/api/x402/*` for x402 Bazaar and AgentCore-style discovery/payment flows.

## Licensing

API outputs (text, metadata) may be redistributed. The underlying legal text is U.S. federal government work (public domain under 17 U.S.C. § 105).

## Machine-readable spec

Machine-readable docs:
- Remote MCP endpoint: https://govlaws.ai/mcp
- x402 resolve endpoint: https://govlaws.ai/api/x402/resolve
- OpenAPI 3.1 spec: https://govlaws.ai/api/openapi.json
- Full LLM guide: https://govlaws.ai/llms-full.txt