Agent Onboarding

Supplier API Quickstart

Minimal path: authenticate, set payout address, create supplier key, verify active status.

Contract details (failure classes, retry policy, smoke flow): AGENT_ONBOARDING_CONTRACT.md

1) Authenticate

Use session auth flow, then call onboarding endpoints with the same cookie/session.

curl -s -X POST https://your-domain/api/auth/token \
  -H 'Content-Type: application/json' \
  --data '{"username":"your_user","password":"your_password"}'

2) Set Payout Address

Use a stable `Idempotency-Key` for retries. Re-send the same key if your client times out.

curl -i -X PUT https://your-domain/api/supplier/payout-address \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-req-001' \
  --cookie 'session=YOUR_SESSION' \
  --data '{"ethAddress":"0xYourBaseAddress"}'

3) Validate + Save Supplier Key

On retry, keep the same `Idempotency-Key` to avoid duplicate key creation from repeated submits. Set `X-Onboarding-Flow: agent` so backend onboarding telemetry records success/fail outcomes.

curl -i -X POST https://your-domain/api/supplier/keys \
  -H 'Content-Type: application/json' \
  -H 'X-Onboarding-Flow: agent' \
  -H 'Idempotency-Key: supplier-key-req-001' \
  --cookie 'session=YOUR_SESSION' \
  --data '{"apiKey":"vce_xxx","label":"main","dailyDiemCap":10}'

4) Verify Setup Status

curl -s https://your-domain/api/supplier/setup-status \
  --cookie 'session=YOUR_SESSION'

`recommended_next_action` returns one of: `set_payout`, `add_key`, `done`.