Programmatische Registrierung: Wallet-Login und API-Key-Erstellung für Agenten und CI

Für autonome KI-Agenten, CI-Pipelines und automatisierte Skripte, die ohne Browser ausgeführt werden, bietet BlockVectra einen programmatischen Login- und Kontoerstellungsworkflow basierend auf Ethereum-Wallet-Signaturen (EIP-4361 / EIP-191).

Vor der Registrierung können Sie zunächst den schlüssellosen öffentlichen Endpunkt https://api.blockvectra.com/v1/robinhood_mainnet/public ausprobieren (nur Wallet-JSON-RPC-Methoden, die Data API erfordert einen Key; Methoden und Limits unterliegen /v1/chains); registrieren Sie ein Konto, falls das Kontingent nicht ausreicht.

Workflow-Übersicht

Der Ablauf für die programmatische Registrierung und Key-Bereitstellung besteht aus vier Schritten:

1. Challenge anfordern: Senden Sie eine Anfrage an POST /auth/siwe/challenge, um eine vom Server generierte Anmelde-Nachricht zu erhalten.
2. Nachricht signieren: Signieren Sie die exakte Nachricht mit einem Ethereum EOA-Wallet mittels EIP-191 (personal_sign).
3. Anmelden / Konto eröffnen: Übermitteln Sie die wortgetreue Nachricht und Signatur an POST /auth/siwe/login. Bei der ersten Anmeldung für ein Wallet wird automatisch ein Konto erstellt (account_created: true). Neue Konten erhalten 30,000,000 CU bei der Registrierung — keine Kreditkarte erforderlich.
4. API key erstellen: Verwenden Sie das Session-Token, um POST /keys aufzurufen und einen API key zu erstellen.

Vollständige ausführbare Beispiele

Beginnen Sie hier: Verwenden Sie einen lokalen Ethereum EOA-Signer, erstellen Sie einen Key und verifizieren Sie ihn mit eth_blockNumber. Für das Bash-Beispiel benötigen Sie curl, jq und Foundry cast. Bewahren Sie Wallet-Zugangsdaten in Ihrer lokalen Signaturumgebung auf.

Vollständige Starter-Vorlage: blockvectra/agent-quickstart

Die folgenden Skripte lesen die Wallet-Zugangsdaten aus, schließen die Challenge- und Login-Sequenz ab, stellen einen API key bereit, exportieren oder geben export BLOCKVECTRA_API_KEY=... für die Umgebungskonfiguration aus und senden eine eth_blockNumber-Verifizierungsanfrage:

Neue Keys benötigen einige Sekunden, um aktiv zu werden; diese Beispiele wiederholen die Anfrage automatisch.

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:-}"
    break
  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 -e --arg status "$RPC_STATUS" '
      ($status == "401" and .error.data.reason == "invalid_api_key") or
      ($status == "503" and .error.code == -32021)
    ' >/dev/null 2>&1; then
    sleep 2
  else
    printf '%s' "$RPC_BODY"
    break
  fi
done

Basis-URL und programmatischer Modus

Alle Authentifizierungs- und Key-Management-Endpunkte verwenden die offizielle Basis-URL:

https://console-api.blockvectra.com/v1

Auslassen des Origin-Headers

Programmatische Anfragen laufen im programmatischen Modus:

• Sowohl die Challenge- (POST /auth/siwe/challenge) als auch die Login-Anfrage (POST /auth/siwe/login) dürfen den Header Origin nicht enthalten (curl und Standard-HTTP-Clients lassen diesen Header standardmäßig weg; fügen Sie ihn nicht manuell hinzu).
• Wenn ein Origin-Header gesendet wird, dieser jedoch keine konfigurierte Web-Konsolen-Domain ist (einschließlich leerer Zeichenkette oder null), gibt die Challenge-Anfrage HTTP 400 invalid_request zurück.
• Wenn der Modus beim Login nicht mit dem Challenge-Modus übereinstimmt (beispielsweise das Anfordern einer programmatischen Challenge ohne Origin und anschließendes Absenden des Logins mit einem Origin-Header oder umgekehrt), gibt die Login-Anfrage HTTP 400 siwe_invalid mit reason: domain_mismatch zurück.

Nachrichtenintegrität und Wallet-Anforderungen

• Wortgetreue Signatur und Übermittlung: Clients müssen den Nachrichtentext exakt so signieren und übermitteln, wie er vom Challenge-Endpunkt zurückgegeben wurde. Ändern Sie weder Leerzeichen, Domain, Chain ID noch andere Felder. Jede Änderung führt zu HTTP 400 siwe_invalid mit reason: signature.
• Unterstützte Wallets: Externally Owned Accounts (EOA) im Ethereum Mainnet (Chain ID 1). Die Signatur muss eine 65-Byte-ECDSA-Signatur sein (personal_sign). Contract-Wallets (EIP-1271) und Smart Accounts werden nicht unterstützt.
• Challenge-Gültigkeit: Jede Challenge-Nonce ist für den einmaligen Gebrauch bestimmt und läuft nach 5 Minuten ab.

Request-Body und Registrierungs-Attribution (optional)

Der Request-Body von POST /auth/siwe/login akzeptiert erforderliche Authentifizierungsparameter und optionale Felder zur Registrierungs-Attribution:

• Erforderliche Felder:
  • message: Der vollständige, vom Challenge-Endpunkt erhaltene SIWE-Nachrichten-String.
  • signature: Die 65-Byte-Hexadezimalsignatur (mit 0x-Präfix), die durch das Signieren von message mittels EIP-191 mit einem Ethereum-Wallet erzeugt wurde.
• Optionale Attributionsfelder (werden nur einmal gespeichert, wenn ein neues Konto erstellt wird; bei nachfolgenden Logins ignoriert):
  • ref: Ein Token für den Kanal in Kleinbuchstaben, das ^[a-z0-9._-]{1,64}$ entspricht (ASCII-Kleinbuchstaben, Ziffern, ., _, -, 1–64 Zeichen). Autonome Agenten können dies beispielsweise auf ihre Framework- oder Laufzeitkennung setzen (z. B. my-agent.v1). Nicht konforme Werte (einschließlich Großbuchstaben, leerer Zeichenketten, übermäßiger Länge oder nicht unterstützter Zeichen) geben HTTP 400 invalid_request ohne Fallumwandlung zurück und verhindern die Kontoerstellung; weglassen oder null übergeben, wenn nicht zutreffend.
  • referrer: Eine Quell-URL oder ein Hostname-String; nur Nicht-String-Typen geben HTTP 400 zurück.

Das Senden undefinierter Felder wie signup_method gibt HTTP 400 invalid_request zurück.

Session-Tokens und API keys

Lebenszyklus von Session-Tokens

• Format: rgs_, gefolgt von 64 hexadezimalen Kleinbuchstaben.
• Gültigkeit: Absolute Lebensdauer von 7 Tagen; läuft nach 24 Stunden Inaktivität automatisch ab.
• Kein Refresh-Token: Wenn ein Session-Token abläuft, initiieren Sie einen neuen Challenge- und Login-Ablauf.
• Header: Übergeben Sie das Session-Token im Request-Header Authorization: Bearer rgs_....

API-Key-Erstellung

• Rufen Sie POST /keys mit dem Session-Token auf, um einen API key zu erstellen (rgw_, gefolgt von 64 Hexadezimalzeichen).
• Pro Konto maximal 20 nicht widerrufene, nicht abgelaufene (active + disabled) Keys; abgelaufene Keys zählen nicht mit. Ein Überschreiten gibt HTTP 409 key_limit_reached mit reason: active_keys und limit: 20 zurück; widerrufen Sie zuerst einen Key. Die Obergrenze gilt über alle Identitäten, Sessions und Chains des Kontos hinweg. Key-Erstellung und -Rotation sind zudem auf 20 pro 24 Stunden begrenzt; ein Überschreiten gibt HTTP 429 rate_limited mit Retry-After: 3600 zurück.
• Optionale Obergrenze und Ablaufzeit: Sie können cu_cap (lebenslange CU-Obergrenze für den Key, die als Soft-Cap fungiert) und eine Ablaufzeit (expires_in_secs oder expires_at, bis zu den maximal durch die Key-Richtlinie zulässigen Tagen) angeben; nach Ablauf oder Erschöpfung der Obergrenze gibt der Server 403 zurück (JSON-RPC -32025, Grund key_expired oder key_cap_exhausted).
• Das Secret api_key wird bei der Erstellung nur ein einziges Mal zurückgegeben. Speichern Sie es unverzüglich sicher in Ihrem Secrets-Manager oder in Umgebungsvariablen.
• Ein API key funktioniert über alle unterstützten Chains hinweg für JSON-RPC und die Data API.

Session oder API key verloren?

Bei BlockVectra ist die Kontoidentität eines Agenten an die bei der Registrierung verwendete Ethereum-Wallet-Adresse gebunden. Wenn Ihr Session-Token abläuft oder ein API key verloren geht bzw. kompromittiert wird, können Sie die vollständige Kontrolle ausschließlich über dieses Wallet wiedererlangen:

1. Erneut mit demselben Wallet authentifizieren: Fordern Sie eine Challenge an, signieren Sie diese mit demselben Wallet und senden Sie die Login-Anfrage ab (POST /auth/siwe/login). Der Server überprüft die Signatur, meldet sich am bestehenden Konto mit account_created: false an und stellt ein neues Session-Token aus.
2. Neuen API key erstellen: Rufen Sie mit dem neuen Session-Token POST /keys mit {"label": "..."} und dem Header Authorization: Bearer <token> auf. Der Endpunkt gibt HTTP 201 mit den Details des erstellten Keys in key und dem einmaligen Secret in api_key zurück. Speichern Sie diesen Key sofort in Ihren Umgebungsvariablen oder Ihrem Secrets-Manager.
3. Alle Keys des Kontos auflisten:
   • Endpunkt: GET /keys
   • Header: Authorization: Bearer <token>
   • Query-Parameter: optional include_revoked=true (wenn true, schließt widerrufene Keys ein; standardmäßig nur aktive/deaktivierte Keys).
   • Antwort: HTTP 200 mit JSON {"items": [...]}. Jedes Element im Array items enthält:
     • key_id: eindeutige Key-Kennung (String)
     • label: Key-Label (String oder null)
     • status: Status ("active", "disabled" oder "revoked")
     • created_at: Erstellungszeitpunkt (ISO-8601-String)
     • revoked_at: Widerrufszeitpunkt (String oder null, falls nicht widerrufen)
4. Ungenutzte oder kompromittierte Keys widerrufen:
   • Endpunkt: POST /keys/{key_id}/revoke (Hinweis: verwendet POST mit der Ziel-key_id im Pfad; leerer Request-Body)
   • Header: Authorization: Bearer <token>
   • Verhalten: idempotent; Keys mit dem Status active oder disabled können beide widerrufen werden. Falls bereits widerrufen, wird unverändert HTTP 200 zurückgegeben. Nach dem Widerruf werden Anfragen mit diesem Key abgelehnt.
   • Antwort: HTTP 200 mit dem widerrufenen Key-Objekt (Felder entsprechen dem obigen Key-Objekt, mit status: "revoked" und einem Zeitstempel in revoked_at).

Sicherheitsempfehlungen

• Kurzlebige Keys verwenden und nach Abschluss widerrufen: Erstellen Sie für automatisierte oder kurzlebige Aufgaben Keys mit geringer Lebensdauer über expires_in_secs und widerrufen Sie diese unmittelbar nach Abschluss der Arbeit über POST /keys/{key_id}/revoke.

Registrierungs-Ratenlimits (signup_rate_limited)

Die Kontoerstellung unterliegt Registrierungs-Ratenlimits. Der Token-Bucket pro IP verfügt über eine Kapazität für 100 Konten und füllt sich mit 100 Konten/Stunde pro IPv4-Adresse oder IPv6-/64-Präfix auf, geteilt zwischen SIWE- und OAuth-Registrierung:

• Bei Überschreiten der Registrierungslimits gibt POST /auth/siwe/login HTTP 429 signup_rate_limited mit einem Retry-After-Header zurück, der die Wartezeit in Sekunden angibt.
• Das Feld reason unterscheidet den Geltungsbereich des Limits:
  • per_ip: Das Registrierungsbudget für das anfragende IP-Präfix ist aufgebraucht.
  • global: Das aggregierte Plattform-Registrierungslimit ist aufgebraucht.
• Registrierungs-Ratenlimits bewerten nur Neuregistrierungen. Bereits bestehende Konten, die sich anmelden, werden durch Registrierungs-Ratenlimits nicht blockiert.

Zugehörige Ressourcen

• Lesen Sie den Integrationsleitfaden für KI-Agenten, um mehr über den schlüssellosen MCP-Server und maschinenlesbare Kontextdateien zu erfahren.
• Konsultieren Sie den Schnellstart für mehrsprachige Client-Beispiele.
• Überprüfen Sie die Fehlerreferenz für vollständige Fehlercodes, Gründe und automatisierte Wiederherstellungsmaßnahmen.

Nächste Schritte

• Senden Sie Ihren ersten JSON-RPC- oder Data-API-Aufruf mit x-api-key: $BLOCKVECTRA_API_KEY.
• Kontoguthaben und Limits prüfen mittels GET /v1/account.
• Folgen Sie dem Leitfaden für programmatische Agent-Aufladungen, um Ihr Guthaben aufrechtzuerhalten.