# Quickstart

For account creation, secure credential setup, first lookup, billing and disconnecting, follow the [complete setup journey](./get-started.md).

For a registered agent connection, use [OAuth](./oauth.md): the user creates or signs in to their Strata account and chooses permissions, with no manual key. Native connector availability depends on the agent platform. For scripts or clients without Strata OAuth, create a personal API key at [the connector dashboard](https://stratatcg.com/connector/dashboard#signup). Store credentials in the client's secret setting, never in a prompt or shared document. Test account and billing journeys with the [sandbox walkthrough](./agent-sandbox.md).

Generate the operation ID once for a new lookup. On a network retry, rerun only the `curl` command with the same body and saved ID.

```bash
STRATA_OPERATION_ID=$(uuidgen)
curl https://stratatcg.com/connector/api/v1/identify \
  -H "Authorization: Bearer $STRATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $STRATA_OPERATION_ID" \
  -d '{"text":"Charizard ex 199/165 151","hints":{"game":"Pokemon"},"enrich":true,"printing":"Foil","language":"English","condition":"Near Mint"}'
```

The default agent workflow identifies and prices together. This example requests an English Foil Near Mint reference, not a condition assessment. Set `enrich:false` when the user asks for identity only. Present the returned product link and image alongside the selected price, source and observation time; see [result presentation](./agent-workflows.md).

Check `results[i].ok` and `confident` before acting on a match. If the identity is ambiguous, show the relevant candidates and request the visible detail that distinguishes them. Do not price a guessed printing.

If the user corrects a result, keep its `resultRef` and send optional feedback
once with a stable idempotency key. Example:

```bash
curl https://stratatcg.com/connector/api/v1/feedback \
  -H "Authorization: Bearer $STRATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: correction-01' \
  -d '{"resultRef":"RESULT_UUID","registry":"shorthand","action":"correct_selection","correctedRef":{"productId":517045}}'
```

Feedback enters review and never directly changes an active identity or link.

For a known raw product, you can skip identification and call `/api/v1/enrich` directly:

```bash
STRATA_OPERATION_ID=$(uuidgen)
curl https://stratatcg.com/connector/api/v1/enrich \
  -H "Authorization: Bearer $STRATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $STRATA_OPERATION_ID" \
  -d '{"productId":517045,"printing":"Foil","language":"English","condition":"Near Mint"}'
```

Check `status`, `selectionRequired`, `sources`, `currency`, and `fetchedAt`. Raw prices describe ungraded markets. Prices may be partial or absent; missing data is not zero.

To identify a slab, use its cert directly:

```bash
STRATA_OPERATION_ID=$(uuidgen)
curl https://stratatcg.com/connector/api/v1/slabs/identify \
  -H "Authorization: Bearer $STRATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $STRATA_OPERATION_ID" \
  -d '{"cert":"149085863","grader":"PSA","enrich":true}'
```

The slab response may include independent ALT graded identity/price, capabilities, and registry progress. A missing raw match does not prevent the graded result. For another grade, call `/api/v1/graded/prices` with the returned `identityRef` and explicit `markets`:

```bash
STRATA_OPERATION_ID=$(uuidgen)
curl https://stratatcg.com/connector/api/v1/graded/prices \
  -H "Authorization: Bearer $STRATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $STRATA_OPERATION_ID" \
  -d '{"ref":{"provider":"alt","entityType":"asset","id":"ALT_ASSET_UUID"},"markets":[{"grader":"PSA","grade":"9"},{"grader":"PSA","grade":"10"}]}'
```

If the registry reports a verified link with printing and language selectors, raw and graded prices can be requested concurrently. Never treat a proposed link as verified. Raw Near Mint is a reference market; slab grade does not establish raw condition.

## Credits and retries

Read `GET /api/billing/status` for public plan prices, limits and checkout availability. For your actual monthly balance and reset, send your personal API key to that endpoint, use the dashboard, or use the OAuth `account` operation. A successful confident identity costs one monthly credit; a usable selected-market price costs one. Slab identity and each graded market follow the same operation rule. `identify` with `enrich:true` reserves two per item and returns unused reservations. During beta, the daily allowance counts attempts; the monthly policy applies after the published transition.

Send a stable `Idempotency-Key` for each logical operation and reuse it with the identical body on network retry. Honor `Retry-After` on 429. Do not split requests or create accounts to evade limits. A retryable provider failure is not a confirmed no-match. Report `requestId` when contacting support.

Full request and response schemas are in [OpenAPI](/connector/openapi.json). See [slab identification](./slabs.md), [graded prices](./graded-prices.md), [slab and cross-market recipes](./recipes.md), [errors and retries](./errors-retries.md), [billing plans](./monthly-plans.md), and [agent instructions](./skills/tcg-identify/SKILL.md).