Programatik Kayıt: Ajanlar ve CI İçin Cüzdanla Oturum Açma ve API Anahtarı Oluşturma

Otonom AI Agent'lar, CI ardışık düzenleri ve tarayıcı olmadan çalışan otomatik betikler için BlockVectra, Ethereum cüzdan imzalarına (EIP-4361 / EIP-191) dayalı programatik bir oturum açma ve hesap açma iş akışı sağlar.

Kaydolmadan önce, anahtarsız genel uç nokta olan https://api.blockvectra.com/v1/robinhood_mainnet/public adresini deneyebilirsiniz (yalnızca cüzdan JSON-RPC yöntemleri, Data API bir anahtar gerektirir; yöntemler ve sınırlar /v1/chains koşullarına tabidir); kota yetersizse bir hesap açın.

İş akışına genel bakış

Programatik kayıt ve anahtar sağlama akışı dört adımdan oluşur:

1. Challenge isteğinde bulunun: Sunucu tarafından oluşturulan bir oturum açma mesajı almak için POST /auth/siwe/challenge uç noktasına bir istek gönderin.
2. Mesajı imzalayın: Bu tam mesajı, bir Ethereum EOA cüzdanı ile EIP-191 (personal_sign) kullanarak imzalayın.
3. Oturum açın / hesap oluşturun: Birebir mesajı ve imzayı POST /auth/siwe/login uç noktasına gönderin. Bir cüzdan için yapılan ilk oturum açma işleminde, otomatik olarak bir hesap oluşturulur (account_created: true). Yeni hesaplar kaydolduklarında 30,000,000 CU kazanır — kredi kartı gerekmez.
4. API anahtarı oluşturun: POST /keys uç noktasını çağırmak ve bir API anahtarı oluşturmak için oturum token'ını kullanın.

Eksiksiz çalıştırılabilir örnekler

Buradan başlayın: yerel bir Ethereum EOA imzalayıcısı kullanın, bir anahtar oluşturun ve bunu eth_blockNumber ile doğrulayın. Bash örneği için curl, jq ve Foundry cast gereklidir. Cüzdan kimlik bilgilerini yerel imzalama ortamınızda tutun.

Eksiksiz başlangıç şablonu: blockvectra/agent-quickstart

Aşağıdaki betikler cüzdan kimlik bilgilerini okur, challenge ve oturum açma dizisini tamamlar, bir API anahtarı sağlar, ortam yapılandırması için export BLOCKVECTRA_API_KEY=... dışa aktarır veya yazdırır ve bir doğrulama eth_blockNumber isteği gönderir:

Yeni anahtarların aktif hale gelmesi birkaç saniye sürer; bu örnekler otomatik olarak yeniden dener.

BASE=https://console-api.blockvectra.com/v1
# $ADDR: Ethereum cüzdan adresi (0x...)
# $PK: cüzdan özel anahtarı, bir gizli bilgi yöneticisinden yüklenir (asla betiklerde sabit kodlamayın)

# 1. Sunucu tarafından oluşturulan SIWE mesajını alın (Origin başlığını atlayın)
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. Mesajı EIP-191 personal_sign ile tam olarak imzalayın
SIG=$(cast wallet sign --private-key "$PK" "$(cat msg.txt)")

# 3. Oturum açmak için birebir mesajı ve imzayı gönderin (Origin başlığını atlayın; ref isteğe bağlıdır)
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. Bir API anahtarı oluşturun (gizli anahtar yalnızca bir kez döndürülür)
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. Anahtarı x-api-key istek başlığında ileterek JSON-RPC'yi çağırın
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

Temel URL ve programatik mod

Tüm kimlik doğrulama ve anahtar yönetimi uç noktaları resmi temel URL'yi kullanır:

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

Origin başlığının atlanması

Programatik istekler programatik modda çalışır:

• Hem challenge (POST /auth/siwe/challenge) hem de oturum açma (POST /auth/siwe/login) istekleri Origin başlığını içermemelidir (curl ve standart HTTP istemcileri varsayılan olarak bu başlığı atlar; manuel olarak eklemeyin).
• Bir Origin başlığı gönderilir ancak yapılandırılmış bir web konsolu etki alanı değilse (boş dize veya null dahil), challenge isteği HTTP 400 invalid_request döndürür.
• Oturum açma anındaki mod challenge moduyla eşleşmezse (örneğin, Origin olmadan programatik bir challenge talep edip ardından bir Origin başlığı ile oturum açma göndermek veya tam tersi), oturum açma isteği reason: domain_mismatch ile HTTP 400 siwe_invalid döndürür.

Mesaj bütünlüğü ve cüzdan gereksinimleri

• Birebir imzalama ve gönderim: İstemciler, mesaj metnini challenge uç noktası tarafından döndürüldüğü şekliyle tam olarak imzalamalı ve göndermelidir. Boşlukları, etki alanını, zincir kimliğini veya herhangi bir alanı değiştirmeyin. Herhangi bir değişiklik, reason: signature ile HTTP 400 siwe_invalid ile sonuçlanır.
• Desteklenen cüzdanlar: Ethereum mainnet (Chain ID 1) Harici Olarak Sahip Olunan Hesaplar (EOA). İmza 65 baytlık bir ECDSA imzası (personal_sign) olmalıdır. Sözleşme cüzdanları (EIP-1271) ve akıllı hesaplar desteklenmez.
• Challenge geçerliliği: Her challenge nonce'ı tek kullanımlıktır ve 5 dakika sonra sona erer.

İstek gövdesi ve kayıt ilişkilendirmesi (isteğe bağlı)

POST /auth/siwe/login istek gövdesi, gerekli kimlik doğrulama parametrelerini ve isteğe bağlı kayıt ilişkilendirme alanlarını kabul eder:

• Gerekli alanlar:
  • message: Challenge uç noktasından alınan eksiksiz SIWE mesaj dizesi.
  • signature: Bir Ethereum cüzdanı ile EIP-191 aracılığıyla message imzalanarak üretilen 65 baytlık onaltılık imza (0x önekli).
• İsteğe bağlı ilişkilendirme alanları (yalnızca yeni bir hesap oluşturulduğunda bir kez kaydedilir; sonraki oturum açmalarda yok sayılır):
  • ref: ^[a-z0-9._-]{1,64}$ ile eşleşen küçük harfli bir kanal token'ı (küçük harf ASCII harfler, rakamlar, ., _, -, 1–64 karakter). Örneğin, otonom ajanlar bunu çerçevelerine veya çalışma zamanı tanımlayıcılarına (ör. my-agent.v1) ayarlayabilir. Uyumsuz değerler (büyük harfler, boş dizeler, fazla uzunluk veya desteklenmeyen karakterler dahil), harf dönüşümü yapılmaksızın HTTP 400 invalid_request döndürür ve hesap oluşturulmasını engeller; geçerli olmadığında atlayın veya null iletin.
  • referrer: Bir kaynak URL veya ana bilgisayar adı dizesi; yalnızca dize olmayan türler HTTP 400 döndürür.

signup_method gibi tanımsız alanların gönderilmesi HTTP 400 invalid_request döndürür.

Oturum token'ları ve API anahtarları

Oturum token'ı yaşam döngüsü

• Biçim: rgs_ ve ardından gelen 64 küçük harfli onaltılık karakter.
• Geçerlilik: Mutlak 7 günlük kullanım ömrü; 24 saatlik boşta kalma süresinden sonra otomatik olarak sona erer.
• Yenileme token'ı (refresh token) yok: Bir oturum token'ının süresi dolduğunda, yeni bir challenge ve oturum açma akışı başlatın.
• Başlık: Oturum token'ını Authorization: Bearer rgs_... istek başlığında iletin.

API anahtarı oluşturma

• Bir API anahtarı oluşturmak için oturum token'ı ile POST /keys uç noktasını çağırın (rgw_ ve ardından gelen 64 onaltılık karakter).
• Hesap başına, iptal edilmemiş ve süresi dolmamış en fazla 20 (active + disabled) anahtar; süresi dolmuş anahtarlar sayılmaz. Bunun aşılması, reason: active_keys ve limit: 20 ile HTTP 409 key_limit_reached döndürür; önce bir anahtarı iptal edin. Bu sınır, hesabın tüm kimlikleri, oturumları ve zincirleri genelinde geçerlidir. Anahtar oluşturma ve rotasyonu da 24 saatte 20 ile sınırlıdır; bunun aşılması, Retry-After: 3600 ile HTTP 429 rate_limited döndürür.
• İsteğe bağlı sınır ve süre sonu: cu_cap (anahtar için ömür boyu CU sınırı, bu esnek bir sınırdır) ve süre sonu (expires_in_secs veya expires_at, anahtar politikası tarafından izin verilen maksimum güne kadar) belirtebilirsiniz; süresi dolduğunda veya sınır tükendiğinde sunucu 403 döndürür (JSON-RPC -32025, neden key_expired veya key_cap_exhausted).
• Gizli api_key oluşturma sırasında yalnızca bir kez döndürülür. Bunu hemen gizli bilgi yöneticinizde veya ortam değişkenlerinizde güvenli bir şekilde saklayın.
• Tek bir API anahtarı, JSON-RPC ve Data API üzerinde desteklenen tüm zincirlerde çalışır.

Oturumunuzu veya API anahtarınızı mı kaybettiniz?

BlockVectra'da, bir ajanın hesap kimliği kayıt sırasında kullanılan Ethereum cüzdan adresine bağlıdır. Oturum token'ınızın süresi dolarsa veya bir API anahtarı kaybolur veya sızdırılırsa, yalnızca o cüzdanı kullanarak tam kontrolü geri kazanabilirsiniz:

1. Aynı cüzdanla yeniden kimlik doğrulaması yapın: Bir challenge talep edin, aynı cüzdanla imzalayın ve oturum açma isteğini (POST /auth/siwe/login) gönderin. Sunucu imzayı doğrular, account_created: false ile mevcut hesapta oturum açar ve yeni bir oturum token'ı düzenler.
2. Yeni bir API anahtarı oluşturun: Yeni oturum token'ı ile {"label": "..."} ve Authorization: Bearer <token> başlığıyla POST /keys çağrısı yapın. Uç nokta, oluşturulan anahtar ayrıntılarını key içinde ve tek seferlik gizli anahtarı api_key içinde içeren HTTP 201 döndürür. Bu anahtarı hemen ortam değişkenlerinizde veya gizli bilgi yöneticinizde saklayın.
3. Hesap için tüm anahtarları listeleyin:
   • Uç nokta: GET /keys
   • Başlık: Authorization: Bearer <token>
   • Sorgu parametresi: isteğe bağlı include_revoked=true (true olduğunda iptal edilen anahtarları içerir; varsayılan olarak yalnızca aktif/devre dışı anahtarları getirir).
   • Yanıt: {"items": [...]} JSON ile HTTP 200. items dizisindeki her öğe şunları içerir:
     • key_id: benzersiz anahtar tanımlayıcısı (dize)
     • label: anahtar etiketi (dize veya null)
     • status: durum ("active", "disabled" veya "revoked")
     • created_at: oluşturma zaman damgası (ISO 8601 dizesi)
     • revoked_at: iptal zaman damgası (dize veya iptal edilmemişse null)
4. Kullanılmayan veya güvenliği ihlal edilmiş anahtarları iptal edin:
   • Uç nokta: POST /keys/{key_id}/revoke (not: yolda hedef key_id ile POST kullanır; boş istek gövdesi)
   • Başlık: Authorization: Bearer <token>
   • Davranış: idempotent; active veya disabled durumundaki anahtarların her ikisi de iptal edilebilir. Zaten iptal edilmişse, değişmeden HTTP 200 döndürür. İptal işleminden sonra, bu anahtarı kullanan istekler reddedilir.
   • Yanıt: İptal edilen anahtar nesnesini döndüren HTTP 200 (alanlar yukarıdaki anahtar nesnesiyle eşleşir; status: "revoked" ve revoked_at içinde bir zaman damgası bulunur).

Güvenlik önerileri

• Kısa süreli anahtarlar kullanın ve işiniz bittiğinde iptal edin: Otomatik veya geçici görevler için expires_in_secs ile kısa ömürlü anahtarlar oluşturun ve çalışma tamamlandığında bunları hemen POST /keys/{key_id}/revoke aracılığıyla iptal edin.

Kayıt hız sınırları (signup_rate_limited)

Hesap oluşturma kayıt hız sınırlarına tabidir. IP başına token kovası 100 hesap kapasitesine sahiptir ve IPv4 adresi veya IPv6 /64 öneki başına saatte 100 hesap hızında yenilenir; SIWE ve OAuth kaydı tarafından paylaşılır:

• Kayıt sınırları aşıldığında, POST /auth/siwe/login beklenecek saniye sayısını belirten bir Retry-After başlığı ile HTTP 429 signup_rate_limited döndürür.
• reason alanı sınır kapsamını ayırt eder:
  • per_ip: istekte bulunan IP öneki için kayıt bütçesi tükenmiştir.
  • global: toplam platform kayıt sınırı tükenmiştir.
• Kayıt hız sınırları yalnızca yeni hesap kayıtlarını değerlendirir. Mevcut hesapların oturum açması kayıt hız sınırları tarafından engellenmez.

İlgili kaynaklar

• Anahtarsız MCP sunucusu ve makine tarafından okunabilir bağlam dosyaları hakkında bilgi edinmek için AI Agent entegrasyon rehberini okuyun.
• Çok dilli istemci örnekleri için Hızlı Başlangıç sayfasını inceleyin.
• Tam hata kodları, nedenleri ve otomatik kurtarma eylemleri için Hata referansını inceleyin.

Sonraki adımlar

• x-api-key: $BLOCKVECTRA_API_KEY ile ilk JSON-RPC veya Data API çağrınızı gönderin.
• GET /v1/account kullanarak hesap bakiyesini ve limitlerini kontrol edin.
• Bakiyeyi korumak için Agent programatik bakiye yükleme rehberini takip edin.