batchin-public

# BatchIn Developer Reference

## Scope

BatchIn Public is the client layer for an evidence-based inference control plane. It contains SDKs, a CLI, an MCP connector, and VaaS verification clients. Provider credentials, customer data, billing ledgers, and hosted route policy stay in the private control plane.

## Discover before calling

Use the authenticated catalog before selecting a model:

```bash
curl https://api.batchin.tech/v1/models \
  -H "Authorization: Bearer $BATCHIN_API_KEY"
```

Only use models whose catalog state reports verified provider smoke, pricing, usage, billing, and account entitlement. Availability can change without a client release. The public repository does not publish a frozen model matrix or prices.

## OpenAI-compatible requests

For supported routes, set the client base URL to `https://api.batchin.tech/v1` and use a model ID returned by the catalog. Compatibility is route- and model-specific. Unsupported parameters, unavailable models, insufficient balance, and provider failures are returned as structured errors.

```python
from batchin import BatchIn

client = BatchIn(api_key="your_batchin_api_key")
models = client.models.list()
model_id = models["data"][0]["id"]
result = client.chat.completions.create(
    model=model_id,
    messages=[{"role": "user", "content": "Hello BatchIn"}],
)
print(result)
```

Multimodal and asynchronous media routes have separate contracts and require an enabled route, output asset, usage record, cost record, and billing record.

## Package map

| Package | Purpose |
| --- | --- |
| `@batchin/sdk` | TypeScript API client, streaming, model discovery, and usage metadata |
| `@batchin/ai-sdk` | Vercel AI SDK provider adapter |
| `batchin` | Python API client and adapters |
| `@batchin/cli` | Authenticated API checks and model discovery |
| `batchin-mcp-server` | MCP catalog, inference, pricing, trace, and receipt tools |
| `@batchin/vaas` | TypeScript receipt and evidence verification client |
| `batchin-vaas` | Python receipt verification client |
| `@batchin/contracts` | Public VaaS Solidity interfaces; deployment is environment-gated |

## VaaS and payments

VaaS verification accepts a real receipt bundle and checks its evidence. Test fixtures are useful for client tests but must be labeled as fixtures. Chain anchoring, x402, USDC, Stripe checkout, refunds, and settlement are readiness-gated; inspect API readiness and ledger records before using those paths in a product.

```bash
npx @batchin/vaas verify <receipt-file-or-record-id> \
  --endpoint https://api.batchin.tech
```

## MCP

Install the connector with `pip install batchin-mcp-server`. The server exposes only the tools registered by the installed package and forwards API errors. Configure the API key through the MCP process environment; never commit it to a client configuration or issue.

## Local checks

```bash
npm ci
npm run typecheck
npm run build
npm run test:ts
npm run test:py
npm run compliance
```

These checks validate client packages and policy scans. They do not perform provider, payment, or chain smoke against production.