Agent Yetkilendirmesi

Piyasa yapıcılar için çoklu anahtar imzalama desteği.

Genel Bakış

Agent yetkilendirmesi, özel bir imzalama anahtarının (agent) bir alım satım cüzdanı adına emir vermesine ve iptal etmesine olanak tanır. Bu şu durumlarda faydalıdır:

• Güvenlik: Alım satım cüzdanı anahtarlarını soğuk depolamada tutun, imzalama için sıcak anahtarlar kullanın
• Operasyonel: Birden fazla ekip üyesi farklı anahtarlarla imzalayabilir
• Otomasyon: Otomatik sistemler özel anahtarlarla imzalayabilir

İki Yetkilendirme Modeli

Hypercall, ürüne bağlı olarak iki ayrı delegasyon sistemine sahiptir:

Ürün	Delegasyon Türü	Depolama	Nasıl Kurulur
Opsiyonlar (REST API)	Agent yetkilendirmesi	Zincir dışı (veritabanı)	POST /approve-agent
Perps (zincir üstü direktifler)	API cüzdanı	Zincir üstü (Exchange kontratı)	hc_update_api_wallet direktifi

Bunlar birbirinden bağımsız sistemlerdir. Opsiyon alım satımı için bir agent onaylamak, onu perps için yetkilendirmez; tersi de geçerlidir.

Opsiyonlar: Agent Yetkilendirmesi (Zincir Dışı)

Agent'lar, bir alım satım cüzdanı adına PlaceOrder ve CancelOrder EIP-712 mesajlarını imzalar. API sunucusu, motora iletmeden önce yetkilendirmeyi kendi veritabanına karşı doğrular.

Perps: API Cüzdanı (Zincir Üstü)

API cüzdanları, perp direktiflerini HypercallAgentSign EIP-712 alanını kullanarak imzalar. Exchange kontratı, yetkilendirmeyi zincir üstünde isApiWalletActive() aracılığıyla doğrular. Direktif imzalamanın tam referansı için EIP-712 İmzalama sayfasına bakın.

Bir API cüzdanı eklemek veya kaldırmak için, hesabın yönetici cüzdanı tarafından imzalanmış bir hc_update_api_wallet direktifi gönderin.

Bu, Hyperliquid'in API cüzdanı modelini yansıtır. Hyperliquid bunları Nonces and API wallets sayfasında agent cüzdanları olarak da adlandırılan API cüzdanları olarak belgeler ve approveAgent'ı Exchange endpoint sayfasında belgeler.

Nonce Yeniden Oynatma (Replay) Koruması

Nonce takibi, Hyperliquid nonce modelini izler. İmzalanan tüm eylemler (emirler, agent onayı/iptali, QP el sıkışmaları) imzalayan başına ortak bir nonce alanı paylaşır. Motor, imzalayan adresi başına en yüksek 100 nonce'u saklar. Yeni bir nonce şu koşullarda kabul edilir:

1. nonce > min(stored_set) -- saklanan en küçük nonce'tan büyük olmalıdır
2. !stored_set.contains(nonce) -- bir kopya olmamalıdır
3. nonce, sunucu zaman damgasına göre (T - 2 gün, T + 1 gün) aralığında olmalıdır

Sıra dışı nonce'lara izin verilir (örneğin, önce nonce 105 sonra 102; her ikisi de küme minimumunun üzerindeyse ikisi de çalışır). Küme 100 girişle sınırlıdır, bu nedenle yeni girişler eklendikçe en eski girişler çıkarılır. Bu, tek bir büyük nonce'un hesabı kilitlemesini önler.

Nonce imzalayanı, EIP-712 mesajını imzalayan adrestir: emirler için API cüzdanı, agent yetkilendirmesi için kurtarılan imzalayan, el sıkışmalar için QP cüzdanı. İstemciler, nonce başlangıç değeri olarak Date.now() (milisaniye cinsinden epoch) kullanmalı ve monotonik olarak artırmalıdır.

Opsiyon Agent Yetkilendirmesi

Doğrudan İmzalama

Eğer signer == wallet ise, emir her zaman yetkilidir (kendi kendine imzalama).

Agent İmzalaması

Eğer signer != wallet ise, imzalayan yetkili bir agent olmalıdır:

• Agent, motora ait yetkilendirme durumunda mevcut olmalıdır
• Yetkilendirmenin süresi dolmamış olmalıdır
• Motor anlık görüntüleri (snapshot) ve motor günlüğü (journal), yeniden başlatmada kalıcı kaynaklardır

Agent Onaylama

Endpoint: POST /approve-agent

İstek: ApproveAgentRequest

{
  "agent": "0x...",
  "nonce": 1,
  "signature": "0x..."
}

İmzalama:

• Cüzdan sahibi ApproveAgent mesajını imzalar
• Cüzdan, kurtarılan imzadan türetilir
• Agent, istekteki agent alanıdır

EIP-712 struct:

struct ApproveAgent {
    address agent;
    uint64 nonce;
}

Yanıt: ApproveAgentResponse

{
  "success": true,
  "error": null
}

Notlar:

• Agent yetkilendirmesi kalıcıdır (veritabanında saklanır)
• expires_at ayarlanmadıkça yetkilendirmenin süresi dolmaz (henüz uygulanmamıştır)

Agent İptali

Endpoint: DELETE /revoke-agent

İstek: RevokeAgentRequest

{
  "agent": "0x...",
  "nonce": 2,
  "signature": "0x..."
}

İmzalama:

• Cüzdan sahibi RevokeAgent mesajını imzalar
• Cüzdan, kurtarılan imzadan türetilir

EIP-712 struct:

struct RevokeAgent {
    address agent;
    uint64 nonce;
}

Yanıt: RevokeAgentResponse

Notlar:

• Motora ait yetkilendirme durumuna günlüğe kaydedilmiş bir RevokeAgent komutu uygular
• Alım satım API'si yetkilendirme kontrolleri arka uç durumunu okur ve alım satım istekleri için iptalleri uygular. Trollbox gönderimi, pozitif agent yetkilendirmesini daha uzun süre önbelleğe alabilir; bu nedenle yakın zamanda iptal edilmiş bir agent, bu önbellek süresi dolana veya en iyi çaba (best-effort) geçersiz kılma ilgili uç (edge) konumuna ulaşana kadar hâlâ gönderi yapabilir. Bu önbellek, alım satım API'si değişikliklerini yetkilendirmez.
• İptalden sonra agent, cüzdan adına artık imza atamaz

Yetkili Agent'ları Getirme

Endpoint: GET /authorized-agents?wallet=...

Sorgu parametreleri:

• wallet (zorunlu)

Yanıt:

{
  "agents": [
    "0x...",
    "0x..."
  ]
}

Notlar:

• Yalnızca aktif, süresi dolmamış agent'ları döndürür
• created_at DESC sırasına göre sıralanır

Agent Kullanımı

Agent ile Emir İmzalama

Bir agent onaylandıktan sonra:

1. Emri agent cüzdanı ile imzalayın: PlaceOrder / CancelOrder mesajlarını imzalamak için agent cüzdanını kullanın
2. Wallet alanını ayarlayın: wallet alanını alım satım cüzdanı adresine ayarlayın (agent adresine değil)
3. Middleware doğrulaması: Middleware, agent'ın o cüzdan için yetkili olduğunu doğrular

Örnek:

// Agent wallet signs the order
const agentSigner = new ethers.Wallet(agentPrivateKey);

const message = {
  wallet: "0x...",  // Trading wallet (not agent)
  symbol: "BTC-20250131-100000-C",
  side: "Buy",
  size: "0.1",
  price: "100.0",
  tif: "gtc",
  clientId: "mm-1",
  nonce: 1
};

// Sign with agent wallet
const signature = await agentSigner._signTypedData(domain, types, message);

// Send request
const response = await fetch('/order', {
  method: 'POST',
  body: JSON.stringify({
    ...message,
    signature
  })
});

Agent ile Toplu Emirler

Toplu (bulk) endpoint'ler, agent yetkilendirmesini öğe bazında doğrular:

• POST /bulk_order içindeki her emir farklı bir agent tarafından imzalanabilir
• Agent yetkilendirmesi öğe bazında kontrol edilir
• Herhangi bir öğe agent yetkilendirmesinde başarısız olursa, o öğe BulkOrderResult içinde hata döndürür

Yetkilendirme Kontrolleri

Middleware (Tekil Emirler)

Endpoint'ler:

• POST /order
• DELETE /order
• DELETE /order_cloid

Kontrol: signature_and_agent_middleware şunları doğrular:

1. İmza kurtarma işlemi başarılıdır
2. İmzalayan yetkilidir (imzalayan == cüzdan VEYA agent yetkilidir)

Handler (Toplu Emirler)

Endpoint'ler:

• POST /bulk_order
• DELETE /bulk_order
• DELETE /bulk_order_cloid

Kontrol: Handler içinde öğe bazında doğrulama:

1. Öğe bazında imza kurtarma
2. Öğe bazında agent yetkilendirme kontrolü

Yetkilendirme Depolaması

Agent yetkilendirmesi motora ait bir durumdur. ApproveAgent ve RevokeAgent komutları günlüğe kaydedilir, motor yeniden oynatması (replay) yoluyla geri yüklenir ve API kontrolleri için okuma anlık görüntüsü aracılığıyla sunulur.

Yetkilendirme Mantığı

İmzalayan yetkilendirmesi açık VEYA mantığıdır:

• Doğrudan imzalama: signer == wallet.
• Agent imzalaması: motor anlık görüntüsü, wallet_address == <wallet> ve agent_address == <signer> için bir yetkilendirme kaydı içerir ve expires_at ya mevcut değildir ya da gelecektedir.

Süre Dolumu

expires_at, motor anlık görüntüsü yetkilendirme kontrolleri tarafından uygulanır. expires_at < NOW() olan agent'lar yetkisiz kabul edilir.

Güvenlik Hususları

1. Agent anahtar güvenliği: Agent özel anahtarlarını koruyun (donanım cüzdanları veya güvenli anahtar yönetimi kullanın)
2. Düzenli denetimler: Yetkili agent'ları GET /authorized-agents aracılığıyla düzenli olarak gözden geçirin
3. Kullanılmayan agent'ları iptal edin: Artık ihtiyaç duyulmayan agent'ları iptal edin
4. Süre dolumu: Onay yolu varsayılan dışı bir süre dolumu sunduğunda, geçici agent yetkilendirmeleri için expires_at kullanın

En İyi Uygulamalar

1. Otomasyon için agent kullanın: Alım satım cüzdanı anahtarlarını soğuk depolamada tutun, otomatik sistemler için agent kullanın
2. Agent kapsamını sınırlayın: Yalnızca erişime ihtiyaç duyan agent'ları onaylayın
3. Agent kullanımını izleyin: Hangi agent'ların emir verdiğini takip edin
4. Hemen iptal edin: Artık ihtiyaç duyulmayan agent'ları derhal iptal edin

Yaygın Sorunlar

"Unauthorized: signer not authorized for wallet"

Neden: Agent onaylanmamış veya yetkilendirmenin süresi dolmuş/iptal edilmiş.

Çözüm: Agent'ı POST /approve-agent aracılığıyla onaylayın veya doğrudan cüzdanla imzalayın.

Agent Yetkilendirmesi Çalışmıyor

Nedenler:

• Agent, motora ait yetkilendirme durumunda mevcut değil
• Yetkilendirme iptal edilmiş
• Yetkilendirmenin süresi dolmuş

Çözüm: Agent durumunu GET /authorized-agents?wallet=... aracılığıyla kontrol edin.