Agent Onboarding Contract

Contract

# Agent Onboarding Contract (Supplier)

Last updated: 2026-03-19

This document defines the stable contract for **supplier** agent onboarding flows.

For **buyer/generation** flows (submitting jobs, x402 payments, polling results), see [`docs/AGENT_API.md`](AGENT_API.md).

## Scope

Goal: onboard a supplier key deterministically with API calls:
1. Authenticate
2. Set payout address
3. Create supplier key
4. Verify setup status

## Stability

- Endpoints in this flow are considered stable for request/response shape.
- Backward-incompatible changes require a documented migration window.
- New response fields may be added; clients should ignore unknown fields.

## Authentication

### POST `/api/auth/token`

The endpoint for non-browser clients. Returns a Bearer token in the body and sets no cookie. (The browser sign-in `/api/auth/login` instead sets an HttpOnly cookie and returns no token — agents use `/api/auth/token`.)

Request:
```json
{
  "username": "your_user",
  "password": "your_password"
}
```

Success: `200`. Returns a `sessionToken` in the body:
```json
{
  "user": { "id": "...", "username": "your_user", "role": "user" },
  "sessionToken": "a1b2c3d4e5f6..."
}
```

**Agent clients: authenticate subsequent requests with `Authorization: Bearer <sessionToken>`.** Cookie-authenticated state-changing requests (`POST`/`PUT`/`PATCH`/`DELETE`) are CSRF-gated and must carry a trusted `Origin` header, which non-browser clients usually omit (→ `403 {"error":"CSRF origin check failed"}`). Bearer auth is exempt.

Failure classes:
- `400`: invalid payload
- `401`: invalid credentials

Retry guidance:
- Do not blindly retry `401`.
- Safe to retry network/5xx errors with exponential backoff.

## Set Payout Address

### PUT `/api/supplier/payout-address`

Headers:
- `Content-Type: application/json`
- `Idempotency-Key: <stable-key-per-logical-request>`
- `X-Onboarding-Flow: agent` (recommended for telemetry)
- `Authorization: Bearer <sessionToken>`

Request:
```json
{
  "ethAddress": "0xYourBaseAddress"
}
```

Success: `200`
```json
{
  "success": true,
  "ethAddress": "0x..."
}
```

Failure classes:
- `400`: invalid address
- `401`: unauthenticated

Retry guidance:
- Reuse the exact same `Idempotency-Key` when retrying.
- Treat `200` as final success for the logical request.

## Create Supplier Key

### POST `/api/supplier/keys`

Headers:
- `Content-Type: application/json`
- `Idempotency-Key: <stable-key-per-logical-request>`
- `X-Onboarding-Flow: agent` (recommended for telemetry)
- `Authorization: Bearer <sessionToken>`

Request:
```json
{
  "apiKey": "vce_xxx",
  "label": "main",
  "dailyDiemCap": 10
}
```

Success: `200`
```json
{
  "first_active_key": true,
  "key": {
    "id": "...",
    "label": "main",
    "daily_diem_cap": 10,
    "is_active": 1,
    "is_valid": 1,
    "venice_diem_balance": 123.45,
    "venice_usd_balance": 67.89,
    "balance_checked_at": "...",
    "created_at": "...",
    "diem_used_today": 0,
    "image_count_today": 0
  }
}
```

Failure classes:
- `400`: validation error (missing key, invalid cap, invalid Venice key)
- `401`: unauthenticated
- `502`: upstream Venice validation unavailable

Retry guidance:
- Reuse the same `Idempotency-Key` for retries of the same logical create.
- Retry `502` and network failures with backoff.
- Do not retry malformed `400` requests without changing payload.

## Setup Status

### GET `/api/supplier/setup-status`

Headers:
- `Authorization: Bearer <sessionToken>`

Success: `200`
```json
{
  "authenticated": true,
  "payout_address_set": true,
  "has_active_key": true,
  "recommended_next_action": "done"
}
```

Failure classes:
- `200` with `authenticated: false` when session missing/invalid

## Retry and Backoff Policy

Recommended client policy:
- Max attempts: 5
- Backoff: exponential with jitter
- Base delay: 300ms
- Cap: 5000ms

Retryable:
- network errors
- `429` (if returned)
- `5xx`
- `502` from key validation endpoint

Non-retryable without payload/session change:
- most `400`
- `401`

## Rate-Limit Expectations

Current guidance for agent clients:
- Keep onboarding calls low-frequency per account.
- Burst onboarding should queue per user/session.
- If `429` appears, apply backoff and preserve idempotency key.

## Telemetry (Agent Flow)

Set `X-Onboarding-Flow: agent` on key-creation requests to emit:
- `agent_key_create_success`
- `agent_key_create_fail`

UI-side quickstart telemetry events:
- `agent_lp_view`
- `agent_quickstart_copy`

## Smoke Validation

Use:
```bash
bun scripts/smoke-agent-onboarding.ts \
  --base-url http://localhost:3000 \
  --username your_user \
  --password your_password \
  --payout-address 0xYourBaseAddress \
  --venice-key vce_xxx
```

The script verifies the full onboarding sequence and exits non-zero on failure.