Como um AI Agent obtém uma API key de blockchain sem navegador: login com carteira (SIWE)
Desenvolvedores e AI Agents obtêm uma API key de blockchain sem navegador em 4 etapas: 3 requisições HTTP à BlockVectra e uma assinatura local da carteira. O cadastro concede 30,000,000 CU; nenhum pagamento é necessário antes.
Um AI Agent obtém uma API key da BlockVectra sem navegador em 4 etapas com 3 requisições HTTP à BlockVectra e uma assinatura local da carteira: solicitar um challenge SIWE, assiná-lo localmente com uma carteira Ethereum, fazer login e chamar POST /keys. O primeiro login cria a conta e concede 30,000,000 CU, então nenhum pagamento é necessário antes. Comece pela primeira chamada abaixo (Verificado em ):
BASE=https://console-api.blockvectra.com/v1
curl -s "$BASE/auth/siwe/challenge" -H 'Content-Type: application/json' \
-d "{\"address\":\"$ADDR\",\"purpose\":\"login\"}"O mesmo fluxo atende AI Agents autônomos, pipelines de CI e scripts executados sem navegador. Ele usa uma mensagem EIP-4361 / SIWE assinada com personal_sign (EIP-191).
Key security
Nunca cole chaves privadas, tokens de sessão ou API keys em conversas com IA nem as passe como argumentos de ferramentas MCP.
Antes de se cadastrar, você pode experimentar o endpoint público sem chave https://api.blockvectra.com/v1/robinhood_mainnet/public primeiro (apenas métodos JSON-RPC de carteira; a Data API exige uma chave; os métodos e limites estão sujeitos a /v1/chains); cadastre uma conta se a cota não for suficiente.
Visão geral do fluxo
O fluxo de registro programático e provisionamento de chaves é composto por quatro etapas:
- Solicitar challenge: envie uma requisição para
POST /auth/siwe/challengepara obter uma mensagem de login gerada pelo servidor. - Assinar mensagem: assine o texto exato da mensagem com uma carteira EOA Ethereum usando EIP-191 (
personal_sign). - Fazer login / abrir conta: envie a mensagem original e a assinatura para
POST /auth/siwe/login. No primeiro login de uma carteira, uma conta é criada automaticamente (account_created: true). Novas contas recebem 30,000,000 CU no cadastro — sem cartão de crédito. - Criar API key: use o token de sessão para chamar
POST /keyse criar uma API key.
Sequência curl mais curta
3 requisições HTTP à BlockVectra mais a assinatura local da carteira (4 etapas), seguidas de uma requisição HTTP autenticada separada com eth_blockNumber para verificar a chave. ADDR é o endereço da carteira (0x...) e PK sua chave privada, carregada de um gerenciador de segredos; é necessário curl, jq e o cast do Foundry. Uma nova chave leva alguns segundos para ficar ativa, então repita um 401 invalid_api_key após uma curta espera (os exemplos completos abaixo repetem automaticamente).
BASE=https://console-api.blockvectra.com/v1
# 1. Challenge: the server returns the exact message to sign
MSG=$(curl -s "$BASE/auth/siwe/challenge" -H 'Content-Type: application/json' \
-d "{\"address\":\"$ADDR\",\"purpose\":\"login\"}" | jq -r .message)
# 2. Sign it with EIP-191 personal_sign
SIG=$(cast wallet sign --private-key "$PK" "$MSG")
# 3. Login: the first sign-in for a wallet creates the account
TOKEN=$(jq -n --arg m "$MSG" --arg s "$SIG" '{message: $m, signature: $s}' |
curl -s "$BASE/auth/siwe/login" -H 'Content-Type: application/json' -d @- | jq -r .session.token)
# 4. Create the API key (the secret is returned only once)
KEY=$(curl -s "$BASE/keys" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"label":"agent-key"}' | jq -r .api_key)
# 5. Call JSON-RPC with the key in the x-api-key header
RESP=$(curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" -H "x-api-key: $KEY" -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' \
-w '\n%{http_code}') &&
printf '%s' "${RESP%$'\n'*}" | jq -es --arg status "${RESP##*$'\n'}" '
if length == 1 and (.[0] | type) == "object" and ($status | test("^2[0-9][0-9]\\z")) and
(.[0] | .jsonrpc == "2.0" and (.id | type) == "number" and .id == 1 and has("error") == false and
(.result | type) == "string" and (.result | test("^0x(0|[1-9a-fA-F][0-9a-fA-F]*)\\z")))
then .[0] else empty end'Exemplos executáveis completos
Comece aqui: use um assinador EOA Ethereum local, crie uma chave e verifique-a com eth_blockNumber. Para o exemplo em Bash, você precisa de curl, jq e cast do Foundry. Mantenha as credenciais da carteira em seu ambiente de assinatura local.
Modelo inicial completo: blockvectra/agent-quickstart
Os scripts a seguir leem as credenciais da carteira, concluem a sequência de challenge e login, provisionam uma API key, exportam ou exibem export BLOCKVECTRA_API_KEY=... para configuração de ambiente e enviam uma requisição de verificação eth_blockNumber:
Novas chaves levam alguns segundos para se tornarem ativas; estes exemplos tentam novamente de forma automática.
BASE=https://console-api.blockvectra.com/v1
# $ADDR: Ethereum wallet address (0x...)
# $PK: wallet private key, loaded from a secrets manager (never hardcode in scripts)
# 1. Fetch server-generated SIWE message (omit Origin header)
curl -s "$BASE/auth/siwe/challenge" -H 'Content-Type: application/json' \
-d "{\"address\":\"$ADDR\",\"purpose\":\"login\"}" > challenge.json
jq -r .message challenge.json > msg.txt
# 2. Sign the exact message with EIP-191 personal_sign
SIG=$(cast wallet sign --private-key "$PK" "$(cat msg.txt)")
# 3. Submit verbatim message and signature (omit Origin header) to log in (ref is optional)
jq -n --rawfile m msg.txt --arg s "$SIG" '{message: ($m | rtrimstr("\n")), signature: $s, ref: "docs-signup"}' |
curl -s "$BASE/auth/siwe/login" -H 'Content-Type: application/json' -d @- > session.json
TOKEN=$(jq -r .session.token session.json)
# 4. Create an API key (the secret is returned only once)
KEY_RESP=$(curl -s "$BASE/keys" \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"label":"agent-key"}')
export BLOCKVECTRA_API_KEY=$(echo "$KEY_RESP" | jq -r .api_key)
# 5. Call JSON-RPC with the key in the x-api-key request header
RPC_DEADLINE=$((SECONDS + 10))
while true; do
RPC_TIMEOUT=$((RPC_DEADLINE - SECONDS))
if ((RPC_TIMEOUT <= 0)); then
printf '%s' "${RPC_BODY:-}"
echo "RPC verification failed: retry budget exhausted" >&2
exit 1
fi
RPC_RESP=$(curl -s --max-time "$RPC_TIMEOUT" -w '\n%{http_code}' "https://api.blockvectra.com/v1/robinhood_mainnet" \
-H "x-api-key: $BLOCKVECTRA_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}') || { rc=$?; echo "request failed (curl exit $rc)" >&2; exit $rc; }
RPC_STATUS=${RPC_RESP##*$'\n'}
RPC_BODY=${RPC_RESP%$'\n'*}
if ((SECONDS + 2 < RPC_DEADLINE)) &&
printf '%s' "$RPC_BODY" | jq -es --arg status "$RPC_STATUS" '
length == 1 and (.[0] | type) == "object" and (
($status == "401" and .[0].error.data.reason == "invalid_api_key") or
($status == "503" and .[0].error.code == -32021))
' >/dev/null 2>&1; then
sleep 2
continue
fi
printf '%s' "$RPC_BODY"
printf '%s' "$RPC_BODY" | jq -es --arg status "$RPC_STATUS" '
length == 1 and (.[0] | type) == "object" and ($status | test("^2[0-9][0-9]\\z")) and
(.[0] | .jsonrpc == "2.0" and (.id | type) == "number" and .id == 1 and has("error") == false and
(.result | type) == "string" and (.result | test("^0x(0|[1-9a-fA-F][0-9a-fA-F]*)\\z")))
' >/dev/null 2>&1 || { echo "RPC verification failed (HTTP $RPC_STATUS)" >&2; exit 1; }
break
doneURL base e modo programático
Todos os endpoints de autenticação e gerenciamento de chaves usam a URL base oficial:
https://console-api.blockvectra.com/v1Omissão do cabeçalho Origin
As requisições programáticas operam no modo programático:
- Tanto a requisição de challenge (
POST /auth/siwe/challenge) quanto a de login (POST /auth/siwe/login) não devem incluir o cabeçalhoOrigin(curle clientes HTTP padrão omitem esse cabeçalho por padrão; não o adicione manualmente). - Se um cabeçalho
Originfor enviado mas não for um domínio configurado do console web (incluindo string vazia ounull), a requisição de challenge retornará HTTP 400invalid_request. - Se o modo no login não coincidir com o modo do challenge (por exemplo, solicitar um challenge programático sem
Origine depois enviar o login com um cabeçalhoOrigin, ou vice-versa), a requisição de login retornará HTTP 400siwe_invalidcomreason: domain_mismatch.
Integridade da mensagem e requisitos da carteira
- Assinatura e envio idênticos: os clientes devem assinar e enviar o texto da mensagem exatamente como retornado pelo endpoint de challenge. Não altere espaços em branco, domínio, Chain ID ou qualquer outro campo. Qualquer modificação resulta em HTTP 400
siwe_invalidcomreason: signature. - Carteiras suportadas: Contas Externamente Proprietárias (EOA) da rede Ethereum mainnet (Chain ID 1). A assinatura deve ser uma assinatura ECDSA de 65 bytes (
personal_sign). Carteiras de contrato (EIP-1271) e contas inteligentes (smart accounts) não são suportadas. - Validade do challenge: cada nonce de challenge é de uso único e expira após 5 minutos.
Corpo da requisição e atribuição de cadastro (opcional)
O corpo da requisição POST /auth/siwe/login aceita parâmetros obrigatórios de autenticação e campos opcionais de atribuição de cadastro:
- Campos obrigatórios:
message: a string completa da mensagem SIWE obtida do endpoint de challenge.signature: a assinatura hexadecimal de 65 bytes (com prefixo0x) produzida ao assinarmessagevia EIP-191 com uma carteira Ethereum.
- Campos opcionais de atribuição (salvos apenas uma vez quando uma nova conta é criada; ignorados em logins subsequentes):
ref: um token de canal em minúsculas correspondente a^[a-z0-9._-]{1,64}$(letras ASCII minúsculas, dígitos,.,_,-, de 1 a 64 caracteres). Por exemplo, agents autônomos podem definir isso como seu identificador de framework ou runtime (ex.:my-agent.v1). Valores fora do padrão (incluindo letras maiúsculas, strings vazias, comprimento excessivo ou caracteres não suportados) retornam HTTP 400invalid_requestsem conversão automática de maiúsculas/minúsculas e impedem a criação da conta; omita ou passenullquando não aplicável.referrer: uma URL de origem ou string de hostname; apenas tipos diferentes de string retornam HTTP 400.
Enviar campos indefinidos como signup_method retorna HTTP 400 invalid_request.
Tokens de sessão e API keys
Ciclo de vida do token de sessão
- Formato:
rgs_seguido por 64 caracteres hexadecimais minúsculos. - Validade: tempo de vida absoluto de 7 dias; expira automaticamente após 24 horas de inatividade.
- Sem token de atualização: quando um token de sessão expirar, inicie um novo fluxo de challenge e login.
- Cabeçalho: passe o token de sessão no cabeçalho de requisição
Authorization: Bearer rgs_....
Criação de API key
- Chame
POST /keyscom o token de sessão para criar uma API key (rgw_seguido por 64 caracteres hexadecimais). - Por conta, no máximo 20 chaves não revogadas e não expiradas (
active+disabled); chaves expiradas não contam. Exceder esse limite retorna HTTP 409key_limit_reachedcomreason: active_keyselimit: 20; revogue uma chave primeiro. O limite se aplica a todas as identidades, sessões e redes da conta. A criação e rotação de chaves também são limitadas a 20 por período de 24 horas; exceder isso retorna HTTP 429rate_limitedcomRetry-After: 3600. - Limite e expiração opcionais: você pode fornecer
cu_cap(limite vitalício de CU para a chave, que é um limite flexível) e expiração (expires_in_secsouexpires_at, até o máximo de dias permitido pela política de chaves); uma vez expirada ou com o limite esgotado, o servidor retorna 403 (JSON-RPC-32025, motivokey_expiredoukey_cap_exhausted). - O segredo
api_keyé retornado apenas uma vez na criação. Armazene-o com segurança imediatamente em seu gerenciador de segredos ou variáveis de ambiente. - Uma API key funciona em todas as redes suportadas no JSON-RPC e na Data API.
Perdeu sua sessão ou API key?
Na BlockVectra, a identidade da conta de um agent é vinculada ao endereço da carteira Ethereum usado no cadastro. Se o token de sessão expirar ou uma API key for perdida ou vazada, você pode recuperar o controle total usando apenas essa carteira:
- Re-autenticar com a mesma carteira: solicite um challenge, assine-o com a mesma carteira e envie a requisição de login (
POST /auth/siwe/login). O servidor verifica a assinatura, faz login na conta existente comaccount_created: falsee emite um novo token de sessão. - Criar uma nova API key: com o novo token de sessão, chame
POST /keyscom{"label": "..."}e o cabeçalhoAuthorization: Bearer <token>. O endpoint retorna HTTP 201 com os detalhes da chave criada emkeye o segredo único emapi_key. Salve essa chave imediatamente em suas variáveis de ambiente ou gerenciador de segredos. - Listar todas as chaves da conta:
- Endpoint:
GET /keys - Cabeçalho:
Authorization: Bearer <token> - Parâmetro de consulta:
include_revoked=trueopcional (quandotrue, inclui chaves revogadas; por padrão, retorna apenas chaves ativas/desativadas). - Resposta: HTTP 200 com JSON
{"items": [...]}. Cada elemento no arrayitemsinclui:key_id: identificador exclusivo da chave (string)label: rótulo da chave (string ounull)status: status ("active","disabled"ou"revoked")created_at: carimbo de data/hora de criação (string ISO 8601)revoked_at: carimbo de data/hora de revogação (string, ounullse não revogada)
- Endpoint:
- Revogar chaves não utilizadas ou comprometidas:
- Endpoint:
POST /keys/{key_id}/revoke(observação: usaPOSTcom okey_idde destino no caminho; corpo de requisição vazio) - Cabeçalho:
Authorization: Bearer <token> - Comportamento: idempotente; chaves com status
activeoudisabledpodem ser revogadas. Se já revogada, retorna HTTP 200 inalterada. Após a revogação, requisições usando essa chave são rejeitadas. - Resposta: HTTP 200 retornando o objeto da chave revogada (os campos coincidem com o objeto da chave acima, com
status: "revoked"e um carimbo de data/hora emrevoked_at).
- Endpoint:
Key and secret security
Armazene chaves privadas de carteiras e API keys em variáveis de ambiente ou em um gerenciador de segredos. Nunca as confirme em repositórios de código, grave-as em logs ou cole-as em conversas de chat com IA.
Recomendações de segurança
- Use chaves de curta duração e revogue ao concluir: para tarefas automatizadas ou efêmeras, crie chaves de curta duração com
expires_in_secse revogue-as imediatamente viaPOST /keys/{key_id}/revokeassim que o trabalho for concluído.
Limites de taxa de cadastro (signup_rate_limited)
A criação de contas está sujeita a limites de taxa de cadastro. O bucket de tokens por IP tem capacidade para 100 contas e se reabastece a 100 contas/hora por endereço IPv4 ou prefixo IPv6 /64, compartilhado entre cadastros via SIWE e OAuth:
- Ao exceder os limites de cadastro,
POST /auth/siwe/loginretorna HTTP 429signup_rate_limitedcom um cabeçalhoRetry-Afterindicando o número de segundos a aguardar. - O campo
reasondiferencia o escopo do limite:per_ip: o orçamento de registro para o prefixo IP solicitante foi esgotado.global: o limite agregado de cadastros da plataforma foi esgotado.
- Os limites de taxa de cadastro avaliam apenas novos registros de contas. Contas existentes fazendo login não são bloqueadas por limites de taxa de cadastro.
FAQ
Preciso pagar ou recarregar antes de obter uma chave?
Não. O primeiro login com a carteira cria a conta e concede 30,000,000 CU. Use o token de sessão do login para criar a chave. Até a primeira recarga, a conta é limitada a 25 chamadas por segundo; veja o que o plano gratuito cobre.
Precisa de navegador, senha ou gas?
Não é necessário navegador. As requisições HTTP usam HTTPS JSON simples sem cabeçalho Origin; assine a mensagem localmente no seu próprio ambiente de carteira. Não há senha; a assinatura da carteira é a credencial. A assinatura é off-chain, então não custa gas nem envia transação. A carteira deve ser uma EOA Ethereum; carteiras de contrato (EIP-1271) não são compatíveis.
E se eu perder a API key?
O segredo é exibido apenas uma vez e não pode ser recuperado. Faça login novamente com a mesma carteira para obter um novo token de sessão, crie uma nova chave e revogue a antiga; veja Perdeu sua sessão ou API key?.
Recursos relacionados
- Leia o guia de integração de AI Agents para conhecer o servidor MCP sem chave e arquivos de contexto legíveis por máquina.
- Consulte o Início rápido para ver exemplos de clientes em várias linguagens.
- Inspecione a referência de erros para ver códigos de erro completos, motivos e ações automáticas de recuperação.
Próximos passos
- Envie sua primeira chamada JSON-RPC ou Data API com
x-api-key: $BLOCKVECTRA_API_KEY. - Consulte o saldo da conta e os limites usando
GET /v1/account. - Siga o guia de recarga programática para Agents para manter o saldo.
Última atualização:
Uma chave, várias redes
A mesma API key funciona em todas as redes compatíveis. Saiba como as URLs são estruturadas, como descobrir redes de forma programática e como saldos e limites são unificados.
Comparação com QuickNode
Use o BlockVectra para leituras RPC ocasionais compatíveis sem assinatura mensal de RPC; o acesso autenticado usa créditos gratuitos elegíveis ou cobrança por uso, com uma recarga mínima de $0.01 excluindo o gas da rede.