# Auth.md — Mindjack Agent Data API

The REST API at /v1 has no signup, no dashboard, no human step and no
account to create. Two ways in, and you can use either without talking
to us. A third applies only to the hosted MCP endpoint, which is built for connector clients and is described at the bottom.

## 1. Pay per call with x402 (no registration at all)

GET /.well-known/x402 lists every priced route, the asset, the network
and the payTo address. Free, no key.

Call a priced route with no credentials. It answers **402**, not 401,
carrying a full `accepts` block and a `PAYMENT-REQUIRED` response
header. Settle it and resend with the proof in a `PAYMENT-SIGNATURE`
header. We verify, settle and serve in the same request.

Sign and submit promptly: a Solana blockhash expires in roughly 60-90
seconds, which is why `maxTimeoutSeconds` is 60. A proof is accepted
exactly once.

## 2. Hold a prepaid balance with an API key

    curl -X POST https://api.mindjack.xyz/v1/keys \
         -H 'Content-Type: application/json' -d '{}'

The key is returned once — save it. Send it as `X-API-Key`.

The key starts empty and buys nothing until funded. GET
/v1/credits/deposit returns the `pay_to` address, free and without a
key. Send USDC there, then POST `{"tx_signature": "..."}` to the same
path with your key. 1 USDC = 2000 credits. A
signature credits exactly once. GET /v1/credits/balance shows what is
left.

Larger deposits earn more credits per dollar. The rate is a function of
the amount and nothing else — there is no account to hold a discount, so
the same transfer is worth the same to everyone:

  starter  $    25  ->     50,000 credits  ($0.50 per 1k)
  builder  $   100  ->    260,000 credits  ($0.38 per 1k, 30% more than base)
  scale    $   500  ->  1,600,000 credits  ($0.31 per 1k, 60% more than base)
  pro      $ 2,000  ->  8,000,000 credits  ($0.25 per 1k, 100% more than base)

A wallet's first settled deposit also carries a one-time 10,000-credit
welcome on a first deposit of $10 or more. Once per paying wallet, not per key.

## 3. OAuth, for the hosted MCP endpoint only

This applies to https://api.mindjack.xyz/mcp and to nothing else. The
REST API above is unchanged: same keys, same x402, same prices, no new
header and no new failure. The npm package is unchanged too, on the
specification's own instruction that stdio clients take credentials
from their environment rather than through this flow.

Connecting, listing tools, ping and server/discover need no
credential. `tools/call` needs one, and answers 401 with a
`WWW-Authenticate` header naming the resource metadata document. From
there a client discovers the authorization server on its own:

    GET /.well-known/oauth-protected-resource
    GET https://mindjack.xyz/.well-known/oauth-authorization-server

OAuth 2.1, authorization code with PKCE (S256 required), one scope
(`mcp:call`). Clients may identify themselves with a Client ID
Metadata Document or register dynamically; both are advertised in the
server metadata. Access tokens last an hour and refresh tokens rotate.

A token is bound to one of your API keys and spends that key's
credits. Revoking the key ends every token issued against it, which is
the fastest way to disconnect a client you no longer trust.

An API key still works on this endpoint exactly as it always has. OAuth
is an additional way in for clients built around a consent screen, not
a replacement for the one you already integrated.

## Things that will trip a client

- Every POST needs `Content-Type: application/json`, including the ones
  with no body. Without it you get 415 BEFORE authentication, from a
  CSRF gate shared with our website — a media-type error where you
  expected a payment challenge. Send `-d '{}'`.
- **401 means you were not at a route.** Real routes answer 402 when
  they want money and 200 when they are free. If you got 401, the path
  does not exist; the 404 body lists the ones that do.
- Nothing here is gated on user agent. Identify yourself honestly.

## What costs nothing

/v1/sample, /v1/coverage, /v1/scorecard, /v1/cohort/fields,
/v1/credits/balance, /llms.txt, /openapi.json, /.well-known/x402.
Failed calls, rate-limited calls and empty results are never charged.

Full endpoint guide: /llms.txt