Autenticação da API - NZOChain

As rotas B2B (/api/v1/...) exigem o header:

X-API-Key: YOUR_API_KEY

Não é sessão cookie e não é Authorization: Bearer nestas rotas de produto. A gestão de projectos, keys e webhooks no portal usa a sessão JWT do developer — contrato separado da API key de produto.

Obter a chave

Entra em developers.nzochain.com.
Cria um projecto.
Gera uma API key (pk_live_...) e guarda-a — trata-a como segredo.

Keys novas recebem por omissão os scopes de produto v1 (inclui wallet.scan). Podes restringir permissões no portal. A app B2C (app.nzochain.com) não usa esta chave: usa ligação de carteira.

Scopes (v1)

Scope	Endpoint
`wallet.scan`	`POST /v1/wallets/risk`
`contract.scan`	`POST /v1/contracts/risk`
`transaction.analyze`	`POST /v1/transactions/analyze` e `.../simulate`
`threat.check`	`POST /v1/threats/check`

Sem o scope exigido → 403 com SCOPE_REQUIRED e o campo required. O gating de plano (Free vs Starter vs Growth) é independente do scope: podes ter o scope e mesmo assim receber PLAN_UPGRADE_REQUIRED.

Exemplo

curl -X POST "https://api.nzochain.com/api/v1/wallets/risk?lang=pt" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"wallet":"0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234","network":"ethereum"}'

const res = await fetch('https://api.nzochain.com/api/v1/wallets/risk?lang=en', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.NZOCHAIN_API_KEY,
  },
  body: JSON.stringify({ wallet: '0x...', network: 'ethereum' }),
});
const { success, data } = await res.json();

Erros de auth

HTTP	Significado
401	`X-API-Key` em falta, inválida ou revogada
403	`SCOPE_REQUIRED` — scope em falta na key

403 de plano (PLAN_UPGRADE_REQUIRED, SIMULATION_QUOTA) e 429 de quota são outra camada — ver erros.

Boas práticas

Só no servidor. Nunca no JavaScript do browser de um dApp público.
Variável de ambiente. Roda chaves se vazarem.
Uma chave por ambiente (dev / prod).
Não existe SDK oficial publicado — usa REST/fetch/curl.