# OpenTrace agent login

You are signing this user into OpenTrace and installing compliance on their paid fetch.

OpenTrace OFAC-screens agent payments, keeps the agent's context, and labels MCC, GL, and vendor into the user's org-scoped ledger after the tx hash is ingested. Screening does not reverse an already-settled payment.

Do all HTTP calls against https://opentrace.pro. Do not use localhost. Do not open AuthKit, GitHub, or Google. This is unhosted Magic Auth on OpenTrace.

## 1. Ask for the user's email

POST a Magic Auth code. WorkOS emails them a 6-digit code; OpenTrace never sees a password.

```bash
curl -sS -X POST 'https://opentrace.pro/api/auth/magic' \
  -H 'Content-Type: application/json' \
  -d '{"email":"USER_EMAIL"}'
```

Tell the user to read the code from their inbox and give it to you.

## 2. Exchange the code for a workspace key

```bash
curl -sS -X POST 'https://opentrace.pro/api/agent/login' \
  -H 'Content-Type: application/json' \
  -d '{"email":"USER_EMAIL","code":"123456"}'
```

The JSON includes `api_key` (`ot_live_…`). Write it to `.env` / `.env.example` as `OPENTRACE_API_KEY`. Do not commit the real secret. Do not print it in full after that.

## 3. Wrap the paid fetch

Install `@opentracedev/client`. Wrap `wrapFetchWithPayment(...)` with `withTrace`. `withTrace` wraps a paid fetch, or a client with `request()` / `fetch()`. MPP / `mppx.fetch` is coming soon. Do not invent it. Do not wrap the wallet or `x402Client`. Call sites stay `fetch(url)`.

```ts
import { withTrace } from "@opentracedev/client";

const fetch = withTrace(wrapFetchWithPayment(globalThis.fetch, x402Client), {
  apiKey: process.env.OPENTRACE_API_KEY!,
});
```

Omit `baseUrl` to POST `https://api.opentrace.pro/v1/traces` with `{ tx_hash, raw_context }`. The wrap must never throw if the trace POST fails.

## Discovery

- Skill: https://opentrace.pro/auth.md
- App: https://opentrace.pro
- Magic Auth: https://opentrace.pro/api/auth/magic
- Agent login: https://opentrace.pro/api/agent/login