# ExChek Docs — Complete Documentation

> API documentation for the ExChek export control classification engine. ECCN classification with Adjudicator-in-the-Loop (AITL), powered by live eCFR data and paid via x402 (USDC on Base).

---

## Overview

- **Docs Home**: https://docs.exchek.us
- **API Base URL**: https://api.exchek.us
- **Website**: https://exchek.us
- **Enterprise**: https://enterprise.exchek.us
- **GitHub (Skills)**: https://github.com/exchekinc/exchekskills
- **Contact**: matt@exchek.us

ExChek provides an API for U.S. export control classification (ECCN, BIS, ITAR). You describe your product; the API determines jurisdiction (EAR vs ITAR) and runs an Order of Review using live eCFR data (15 CFR Part 774 and 22 CFR Part 121). A human reviews and refines each step until the classification is approved, then receives an audit-ready report.

### Key Features

- **First classification free** — One free classification per wallet; then $10 per classification via x402.
- **Live eCFR** — Part 774 (CCL) and Part 121 (USML) with snapshot fallback when the live API is unavailable.
- **Adjudicator-in-the-Loop (AITL)** — You confirm jurisdiction and final ECCN; the API guides the flow.
- **Audit-ready reports** — Stored and linked when Supabase is configured.

---

## Quickstart

Get your first classification in three steps.

### Step 1: Install the ExChek Skills

ExChek skills are plain-text files. Any AI agent can use them directly.

**Any agent:** Point your agent to `github.com/exchekinc/exchekskills/skills`

**Claude Code:** `/install github:exchekinc/exchekskills`

**Cursor:** `git clone https://github.com/exchekinc/exchekskills`

The skills instruct the agent to call api.exchek.us endpoints, relay prompts to you, and send your confirmations or feedback back to the API until the classification is approved and the report is generated.

### Step 2: Fund Your Wallet

Fund your wallet with USDC on Base (eip155:8453).

**Ways to get USDC on Base:**
- **Base network** — Bridge or buy USDC directly on Base.
- **Coinbase** — Buy or transfer USDC and send to your wallet on Base.
- **Pay Sponge / Ampersand / agent payment gateways** — Use an agent-compatible funding flow (PaySponge or Ampersand) to top up the wallet your agent uses.

After funding, the agent uses `npx awal@2.0.3 x402 pay` (or similar) to pay the API when calling paid endpoints.

### Step 3: Start a Classification

Try the first-free endpoint with your wallet address:

```bash
# First classification free (no payment)
curl -X POST https://api.exchek.us/api/classify/start-free \
  -H "Content-Type: application/json" \
  -d '{"walletAddress": "0xYourWalletAddress"}'

# Or pay $10 (x402) to start
# Use: npx awal@2.0.3 x402 pay https://api.exchek.us/api/classify/start -X POST -d '{}'
```

Use the returned `jobId` in all subsequent session requests (submit-info, confirm-jurisdiction, request-oor, approve).

---

## API Reference

**Base URL:** `https://api.exchek.us`

Paid endpoints use the x402 payment protocol (USDC on Base). Session endpoints require a valid `jobId` from a paid or first-free start.

### GET /health

Health check. No payment. Returns `{ "status": "ok", "service": "exchek-api" }`.

### POST /api/classify/start-free

First classification free. No payment.

**Body:** `{ "walletAddress": "0x..." }`

Returns 402 if this wallet has already used the free classification. Returns `jobId` and `promptForUser` on success.

### POST /api/classify/start

**x402 paid ($10).** Start a new AITL classification.

**Returns:** `jobId`, `nextStep`, `promptForUser`.

### POST /api/classify/jurisdiction

**x402 paid ($2).** Determine jurisdiction (BIS vs ITAR) from item description.

**Body:** `description`, `specifications`, `intendedUse`, `notes`.

**Returns:** `jurisdiction`, `rationale`, `citations`, `confidence`.

### POST /api/classify/submit-info

No payment. Submit item details and receive jurisdiction determination.

**Body:** `jobId`, `description`, `specifications`, `intendedUse`, `notes`.

Runs jurisdiction analysis and returns determination. Ask user to confirm or refine.

### POST /api/classify/confirm-jurisdiction

No payment. Confirm or refine jurisdiction determination.

**Body:** `jobId`, `confirmed: true` or `feedback`.

Repeat until confirmed.

### POST /api/classify/request-oor

No payment. Run Order of Review using Part 774 and Part 121.

**Body:** `jobId`.

**Returns:** Proposed ECCN and citations.

### POST /api/classify/refine-oor

No payment. Refine OOR result with expert feedback.

**Body:** `jobId`, `feedback`.

### POST /api/classify/approve

No payment. Finalize classification, generate and store report.

**Body:** `jobId`.

**Returns:** `reportUrl` when Supabase is configured.

### Error Codes

| Code | Meaning |
|---|---|
| 400 | Bad request (e.g., missing jobId) |
| 402 | Payment required (x402) or first free already used |
| 404 | Job not found |
| 500 | Server error |
| 503 | Regulatory data (eCFR) temporarily unavailable |

---

## AITL (Adjudicator-in-the-Loop) Flow

The API drives a structured 6-step flow. The agent calls the API and relays prompts to the user; the user confirms or provides feedback until the classification is approved.

### Step 1: Start

Call `POST /api/classify/start-free` (with `walletAddress`) or paid `POST /api/classify/start`. You get a `jobId` and a prompt asking for item description, specs, intended use.

### Step 2: Submit Item Info

Agent sends your description to `POST /api/classify/submit-info` with `jobId`, `description`, `specifications`, `intendedUse`, `notes`. API returns jurisdiction (BIS or ITAR) and rationale.

### Step 3: Confirm Jurisdiction

You confirm or give feedback. Agent calls `POST /api/classify/confirm-jurisdiction` with `confirmed: true` or `feedback`. Repeat until confirmed.

### Step 4: Order of Review

Agent calls `POST /api/classify/request-oor`. API runs OOR using Part 774 and Part 121 and returns proposed ECCN and citations.

### Step 5: Review and Refine

You approve or give feedback. Agent calls `POST /api/classify/refine-oor` with `feedback` if needed. Repeat until satisfied.

### Step 6: Approve

Agent calls `POST /api/classify/approve`. API stores the classification and generates an audit-ready report; returns `reportUrl` when configured.

All session steps (submit-info, confirm-jurisdiction, request-oor, refine-oor, approve) require the same `jobId` in the request body. Only start (and optionally jurisdiction) are paid.

---

## Payment Protocol

ExChek API charges in USDC on Base (eip155:8453) via the x402 payment protocol.

### Pricing

- **First classification**: Free (one per wallet)
- **Subsequent classifications**: $10 per classification (POST /api/classify/start)
- **Standalone jurisdiction**: $2 per determination (POST /api/classify/jurisdiction)
- **Session endpoints**: Included with the classification fee

### How x402 Payment Works

1. Agent calls a paid endpoint
2. API returns 402 with payment requirements (amount, recipient, network)
3. Agent signs and submits USDC payment on Base
4. Agent retries the request with payment proof
5. API processes the request

---

## Integration

### Any AI Agent (Recommended)

ExChek skills are plain-text instruction files. Any agent that can read text and make HTTP requests can use them. Point your agent to: `github.com/exchekinc/exchekskills/skills`

### Claude Code

```bash
/install github:exchekinc/exchekskills
```

### Cursor

```bash
git clone https://github.com/exchekinc/exchekskills
```

### How Skills Work

The skills instruct the agent to:
1. Call api.exchek.us endpoints
2. Relay prompts to the user
3. Send user confirmations or feedback back to the API
4. Continue until classification is approved and report is generated

### Direct API Integration

Any HTTP client can call the API. Paid endpoints require x402 payment handling. Use the AITL flow (start → submit-info → confirm-jurisdiction → request-oor → refine-oor → approve) for full classifications.

---

## Related Sites

- **ExChek Website**: https://exchek.us — Product overview, pricing, and getting started
- **ExChek Enterprise**: https://enterprise.exchek.us — Custom implementation, integrations, and support
- **API Server**: https://api.exchek.us — Live API endpoint
- **GitHub**: https://github.com/exchekinc/exchekskills — Open-source skills repository