Pendaftaran terprogram: masuk dengan dompet dan buat API key untuk Agent dan CI

Untuk AI Agent otonom, pipeline CI, dan skrip otomatis yang berjalan tanpa browser, BlockVectra menyediakan alur masuk dan pembukaan akun secara terprogram berdasarkan tanda tangan dompet Ethereum (EIP-4361 / EIP-191).

Sebelum mendaftar, Anda dapat terlebih dahulu mencoba endpoint publik tanpa API key https://api.blockvectra.com/v1/robinhood_mainnet/public (hanya metode JSON-RPC dompet, Data API memerlukan API key; metode dan batas mengikuti /v1/chains); daftar akun jika kuotanya tidak cukup.

Gambaran alur kerja

Alur pendaftaran terprogram dan penyediaan API key terdiri dari empat langkah:

1. Minta challenge: Kirim permintaan ke POST /auth/siwe/challenge untuk mendapatkan pesan masuk yang dibuat server.
2. Tandatangani pesan: Tandatangani pesan tersebut persis sebagaimana diterima dengan dompet Ethereum EOA menggunakan EIP-191 (personal_sign).
3. Masuk / buka akun: Kirim pesan tanpa perubahan beserta tanda tangannya ke POST /auth/siwe/login. Saat dompet pertama kali masuk, akun dibuat secara otomatis (account_created: true). Akun baru mendapatkan 30,000,000 CU saat pendaftaran — tanpa kartu kredit.
4. Buat API key: Gunakan token sesi untuk memanggil POST /keys dan membuat API key.

Contoh lengkap yang dapat dijalankan

Mulai di sini: gunakan penanda tangan Ethereum EOA lokal, buat API key, dan verifikasi dengan eth_blockNumber. Untuk contoh Bash, Anda memerlukan curl, jq, dan Foundry cast. Simpan kredensial dompet dalam lingkungan penandatanganan lokal Anda.

Templat awal lengkap: blockvectra/agent-quickstart

Skrip berikut membaca kredensial dompet, menyelesaikan urutan challenge dan login, menyediakan API key, mengekspor atau mencetak export BLOCKVECTRA_API_KEY=... untuk konfigurasi lingkungan, dan mengirim permintaan verifikasi eth_blockNumber:

API key baru memerlukan beberapa detik untuk aktif; contoh ini mencoba ulang secara otomatis.

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

Base URL dan mode terprogram

Semua endpoint autentikasi dan pengelolaan API key menggunakan base URL resmi:

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

Tidak menyertakan header Origin

Permintaan terprogram beroperasi dalam mode terprogram:

• Permintaan challenge (POST /auth/siwe/challenge) dan login (POST /auth/siwe/login) tidak boleh menyertakan header Origin (curl dan klien HTTP standar tidak menyertakan header ini secara default; jangan menambahkannya secara manual).
• Jika header Origin dikirim tetapi bukan domain konsol web yang dikonfigurasi (termasuk string kosong atau null), permintaan challenge mengembalikan HTTP 400 invalid_request.
• Jika mode saat login tidak sesuai dengan mode challenge (misalnya meminta challenge terprogram tanpa Origin, lalu mengirim login dengan header Origin, atau sebaliknya), permintaan login mengembalikan HTTP 400 siwe_invalid dengan reason: domain_mismatch.

Integritas pesan dan persyaratan dompet

• Tanda tangan dan pengiriman tanpa perubahan: Klien harus menandatangani dan mengirim teks pesan persis sebagaimana dikembalikan endpoint challenge. Jangan mengubah spasi, domain, chain ID, atau bidang apa pun. Perubahan apa pun menghasilkan HTTP 400 siwe_invalid dengan reason: signature.
• Dompet yang didukung: Externally Owned Accounts (EOA) Ethereum mainnet (Chain ID 1). Tanda tangan harus berupa tanda tangan ECDSA 65 byte (personal_sign). Dompet kontrak (EIP-1271) dan smart account tidak didukung.
• Masa berlaku challenge: Setiap nonce challenge hanya dapat digunakan sekali dan kedaluwarsa setelah 5 menit.

Body permintaan dan atribusi pendaftaran (opsional)

Body permintaan POST /auth/siwe/login menerima parameter autentikasi wajib dan bidang atribusi pendaftaran opsional:

• Bidang wajib:
  • message: String pesan SIWE lengkap yang diperoleh dari endpoint challenge.
  • signature: Tanda tangan heksadesimal 65 byte (berawalan 0x) yang dihasilkan dengan menandatangani message melalui EIP-191 menggunakan dompet Ethereum.
• Bidang atribusi opsional (disimpan hanya sekali saat akun baru dibuat; diabaikan saat login berikutnya):
  • ref: Token kanal dalam huruf kecil yang cocok dengan ^[a-z0-9._-]{1,64}$ (huruf ASCII kecil, angka, ., _, -, 1–64 karakter). Misalnya, Agent otonom dapat mengisinya dengan pengenal framework atau runtime mereka (misalnya my-agent.v1). Nilai yang tidak sesuai (termasuk huruf besar, string kosong, panjang berlebih, atau karakter yang tidak didukung) mengembalikan HTTP 400 invalid_request tanpa konversi huruf besar/kecil dan mencegah pembuatan akun; jangan sertakan atau kirim null jika tidak berlaku.
  • referrer: String URL atau hostname sumber; hanya tipe selain string yang mengembalikan HTTP 400.

Mengirim bidang yang tidak didefinisikan seperti signup_method mengembalikan HTTP 400 invalid_request.

Token sesi dan API key

Siklus hidup token sesi

• Format: rgs_ diikuti 64 karakter heksadesimal huruf kecil.
• Masa berlaku: Masa hidup absolut 7 hari; kedaluwarsa otomatis setelah 24 jam tanpa aktivitas.
• Tanpa refresh token: Saat token sesi kedaluwarsa, mulai alur challenge dan login baru.
• Header: Kirim token sesi dalam header permintaan Authorization: Bearer rgs_....

Pembuatan API key

• Panggil POST /keys dengan token sesi untuk membuat API key (rgw_ diikuti 64 karakter heksadesimal).
• Per akun, maksimal 20 API key yang belum dicabut dan belum kedaluwarsa (active + disabled); API key yang kedaluwarsa tidak dihitung. Melampaui batas ini mengembalikan HTTP 409 key_limit_reached dengan reason: active_keys dan limit: 20; cabut satu API key terlebih dahulu. Batas ini berlaku di semua identitas, sesi, dan chain akun. Pembuatan dan rotasi API key juga dibatasi hingga 20 per 24 jam; melampaui batas ini mengembalikan HTTP 429 rate_limited dengan Retry-After: 3600.
• Batas dan kedaluwarsa opsional: Anda dapat menyediakan cu_cap (batas CU selama masa hidup API key, yang merupakan batas lunak) dan kedaluwarsa (expires_in_secs atau expires_at, hingga jumlah hari maksimum yang diizinkan kebijakan API key); setelah kedaluwarsa atau batas habis, server mengembalikan 403 (JSON-RPC -32025, alasan key_expired atau key_cap_exhausted).
• Secret api_key hanya dikembalikan sekali saat pembuatan. Segera simpan dengan aman dalam pengelola secret atau variabel lingkungan.
• Satu API key berlaku di semua chain yang didukung pada JSON-RPC dan Data API.

Kehilangan sesi atau API key?

Di BlockVectra, identitas akun Agent terikat pada alamat dompet Ethereum yang digunakan saat pendaftaran. Jika token sesi kedaluwarsa atau API key hilang atau bocor, Anda dapat memulihkan kendali penuh hanya menggunakan dompet tersebut:

1. Autentikasi ulang dengan dompet yang sama: Minta challenge, tandatangani dengan dompet yang sama, lalu kirim permintaan login (POST /auth/siwe/login). Server memverifikasi tanda tangan, masuk ke akun yang sudah ada dengan account_created: false, dan menerbitkan token sesi baru.
2. Buat API key baru: Dengan token sesi baru, panggil POST /keys dengan {"label": "..."} dan header Authorization: Bearer <token>. Endpoint mengembalikan HTTP 201 dengan detail API key yang dibuat dalam key dan secret sekali tampil dalam api_key. Segera simpan API key ini dalam variabel lingkungan atau pengelola secret.
3. Daftar semua API key akun:
   • Endpoint: GET /keys
   • Header: Authorization: Bearer <token>
   • Parameter kueri: include_revoked=true opsional (saat true, menyertakan API key yang dicabut; secara default hanya API key aktif/dinonaktifkan).
   • Respons: HTTP 200 dengan JSON {"items": [...]}. Setiap elemen dalam array items mencakup:
     • key_id: pengenal unik API key (string)
     • label: label API key (string atau null)
     • status: status ("active", "disabled", atau "revoked")
     • created_at: waktu pembuatan (string ISO 8601)
     • revoked_at: waktu pencabutan (string, atau null jika belum dicabut)
4. Cabut API key yang tidak digunakan atau bocor:
   • Endpoint: POST /keys/{key_id}/revoke (catatan: menggunakan POST dengan key_id tujuan pada jalur; body permintaan kosong)
   • Header: Authorization: Bearer <token>
   • Perilaku: idempoten; API key berstatus active maupun disabled dapat dicabut. Jika sudah dicabut, mengembalikan HTTP 200 tanpa perubahan. Setelah pencabutan, permintaan menggunakan API key tersebut ditolak.
   • Respons: HTTP 200 yang mengembalikan objek API key yang dicabut (bidang sesuai objek API key di atas, dengan status: "revoked" dan waktu pada revoked_at).

Rekomendasi keamanan

• Gunakan API key berumur pendek dan cabut setelah selesai: Untuk tugas otomatis atau sementara, buat API key berumur pendek dengan expires_in_secs dan segera cabut melalui POST /keys/{key_id}/revoke setelah pekerjaan selesai.

Batas laju pendaftaran (signup_rate_limited)

Pembuatan akun tunduk pada batas laju pendaftaran. Token bucket per IP memiliki kapasitas 100 akun dan terisi ulang dengan laju 100 akun/jam per alamat IPv4 atau prefiks IPv6 /64, digunakan bersama oleh pendaftaran SIWE dan OAuth:

• Saat melampaui batas pendaftaran, POST /auth/siwe/login mengembalikan HTTP 429 signup_rate_limited dengan header Retry-After yang menunjukkan jumlah detik untuk menunggu.
• Bidang reason membedakan cakupan batas:
  • per_ip: jatah pendaftaran untuk prefiks IP peminta telah habis.
  • global: batas agregat pendaftaran platform telah habis.
• Batas laju pendaftaran hanya mengevaluasi pendaftaran akun baru. Login akun yang sudah ada tidak diblokir oleh batas laju pendaftaran.

Sumber daya terkait

• Baca panduan integrasi AI Agent untuk mempelajari server MCP tanpa API key dan berkas konteks yang dapat dibaca mesin.
• Tinjau Panduan Cepat untuk contoh klien dalam berbagai bahasa pemrograman.
• Periksa referensi error untuk kode error lengkap, alasan, dan tindakan pemulihan otomatis.

Langkah berikutnya

• Kirim panggilan JSON-RPC atau Data API pertama Anda dengan x-api-key: $BLOCKVECTRA_API_KEY.
• Periksa saldo akun dan batas menggunakan GET /v1/account.
• Ikuti panduan top up terprogram Agent untuk menjaga saldo.