Partner API v1

Embed NAI confidence scoring directly into your underwriting pipeline. Server-to-server, bearer-token authenticated.

Issue a test key from your Organization dashboard at /org/api-keys — you can copy it anytime. Live keys require KYB approval.

Authentication

Pass your key in the Authorization header as a Bearer token. Test keys (nai_test_…) resolve magic addresses and never touch live scoring infrastructure. Live keys (nai_live_…) require KYB approval and count against your plan quota.

Authorization: Bearer nai_test_<your-key>

POST /v1/score

Score a wallet address and return a confidence-scored, risk-rated Net Asset Index profile.

Request body

{
  "walletAddress": "0x…"  // required — EIP-55 checksummed address
}

Response (200)

{
  "grade": "A-",
  "maxLtvPct": 65,
  "maxLoanUsd": 45800,
  "totalUsd": 100000,
  "holdings": [...],
  "signals": [...],
  "control": {
    "controlScore": 91,
    "custodyMix": { "EOA": 70, "SMART_ACCOUNT": 0, "MULTISIG": 0, "STAKED": 30, "CEX": 0 },
    "stablecoinPct": 27
  },
  "snapshotIso": "2025-01-15T09:30:00Z",
  "summary": "...",
  "scoringModelVersion": "wallet-v1.1",
  "requestId": "req_…"
}

Magic test addresses

These addresses always return deterministic responses when called with a TEST key — no real blockchain lookup is performed. Use them for iteration and CI without burning live RPC quota.

Address	Archetype	Grade	Description
0x000000000000000000000000000000000000a111	stablecoin-earner	A+	100% EOA (controlScore 100) — remittance recipient or freelancer holding USDC on Base
0x000000000000000000000000000000000000a112	treasury-holder	A	50% MULTISIG + 50% EOA (controlScore 95) — business/DAO treasury with Gnosis Safe
0x000000000000000000000000000000000000b121	crypto-native	A-	70% EOA + 30% STAKED (controlScore 91) — diversified DeFi user with Lido staking
0x000000000000000000000000000000000000c131	degen-holder	C	80% CEX + 20% EOA (controlScore 52) — speculator with holdings mostly on centralized exchange
0x000000000000000000000000000000000000d141	error	422	Triggers insufficient_balance error — total holdings below $10 USD minimum
0x000000000000000000000000000000000000e151	error	429	Triggers rate-limited error — simulated quota exhaustion response
0x000000000000000000000000000000000000f161	error	502	Triggers rpc_upstream_error — simulated blockchain RPC failure

Error codes

Status	Meaning
400	Malformed request body
401	Missing or invalid API key
403	Key revoked or organization suspended
422	Invalid wallet address format
429	Rate limit or daily quota exceeded
500	Internal scoring failure

Rate limits

TEST keys: 240 requests / day, 10 requests / IP / hour. LIVE keys are plan-dependent (default 10 000 / day). The X-RateLimit-Remaining and X-RateLimit-Reset headers are returned on every response.

Hit a 429? Backoff per the X-RateLimit-Reset header. Magic addresses do not count against the per-IP cap.

Snippets

For copy-paste curl, Node.js, Python, and Go examples, see the Quickstart tab in your dashboard — it auto-substitutes your test key.

Reading attestations (v1 + v2)

NAI issues EAS attestations under two schema versions in parallel. Always branch on schemaVersion when reading:

function verifyCredential(attestation) {
  const schemaVersion = decode(attestation).schemaVersion;
  if (schemaVersion === "1.0") return decodeV1(attestation);
  if (schemaVersion === "2.0") return decodeV2(attestation); // includes control fields
  throw new Error(`Unknown schema version: ${schemaVersion}`);
}

V2 adds controlScore, five custody-share uint8 fields (sum to 100), and stablecoinPct. V1 credentials remain valid indefinitely — no forced re-issuance.