Ajan Yetkilendirmesi

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

Genel Bakış

Ajan yetkilendirmesi, özel bir imzalama anahtarının (ajan) bir işlem cüzdanı adına emir vermesine ve emir iptal etmesine olanak tanır. Bu özellik şu durumlarda faydalıdır:

• Güvenlik: İşlem 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ı yetki devri sistemine sahiptir:

Ürün	Yetki Devri Türü	Depolama	Nasıl Kurulur
Opsiyonlar (REST API)	Ajan yetkilendirmesi	Hypercall motor durumu	POST /approve-agent
Perp'ler	API cüzdanı	Zincir üstü (Account sözleşmeniz)	hc_update_api_wallet direktifi

Bunlar birbirinden bağımsız sistemlerdir. Bir ajanı opsiyon işlemleri için onaylamak, onu perp'ler için yetkilendirmez; bunun tersi de geçerlidir.

Opsiyonlar: Ajan Yetkilendirmesi (Zincir Dışı)

Ajanlar, bir işlem cüzdanı adına PlaceOrder ve CancelOrder EIP-712 mesajlarını imzalar. API, emir motora ulaşmadan önce ajanı motorun yetkilendirme durumuna göre kontrol eder.

Perp'ler: API Cüzdanı (Zincir Üstü)

API cüzdanları, perp emirlerini ve iptallerini HypercallApiSign EIP-712 alanında imzalar. Hypercall, emri kabul etmeden önce imzalayanı Account sözleşmenize (isApiWalletActive()) göre kontrol eder. TEE rotasında (uygulamada varsayılan, API istemcileri için ise isteğe bağlı), Account'unuz için ayrı bir Hyperliquid işlem anahtarı tutan güvenli bir enclave yerel emri imzalar ve gönderir; uygulamada gelişmiş bir ayar olan akıllı sözleşme rotasında ise emir Account sözleşmeniz üzerinden geçer. İmzalama referansı için EIP-712 İmzalama, akış için Perp'ler 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 yapı, Hyperliquid'in API cüzdanı modelini yansıtır. Hyperliquid bunları Nonces and API wallets sayfasında ajan cüzdanları olarak da adlandırılan API cüzdanları şeklinde belgeler ve approveAgent işlemini Exchange endpoint sayfasında açıklar.

Nonce Tekrar Koruması

Nonce takibi, Hyperliquid nonce modelini izler. İmzalı tüm eylemler (emirler, ajan onayı/iptali, QP el sıkışmaları) imzalayan başına ortak bir nonce alanını paylaşır. Motor, her imzalayan adresi için en yüksek 100 nonce değerini saklar. Yeni bir nonce şu koşullarda kabul edilir:

1. !stored_set.contains(nonce): tekrar değildir
2. Küme 100 kayda ulaştığında nonce > min(stored_set): saklanan en küçük nonce değerinden büyüktür
3. nonce, sunucu zaman damgasının (T - 2 gün, T + 1 gün) aralığı içindedir

Sırası bozuk nonce değerlerine izin verilir (örneğin, her ikisi de küme minimumunun üzerindeyse önce 105 sonra 102 nonce değerleri çalışır). Küme 100 kayıtla sınırlıdır, bu nedenle yeni kayıtlar eklendikçe en eski kayıtlar çıkarılır. Bu, tek bir büyük nonce nedeniyle hesabın kullanılamaz hale gelmesini önler.

Nonce imzalayanı, EIP-712 mesajını imzalayan adrestir: emirler için API cüzdanı, ajan 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 değeri monoton olarak artırmalıdır.

Opsiyon Ajan Yetkilendirmesi

Doğrudan İmzalama

signer == wallet ise emir her zaman yetkilidir (kendi kendine imzalama).

Ajan ile İmzalama

signer != wallet ise imzalayan yetkili bir ajan olmalıdır:

• Ajan, motorun sahip olduğu yetkilendirme durumunda bulunmalıdır
• Yetkilendirmenin süresi dolmamış olmalıdır
• Motor snapshot'ları ve motor journal'ı, yeniden başlatma için kalıcı kaynaklardır

Ajan Onaylama

Uç nokta: 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
• Ajan, istekteki agent alanıdır

EIP-712 yapısı:

struct ApproveAgent {
    address agent;
    uint64 nonce;
}

Yanıt: ApproveAgentResponse

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

Notlar:

• Ajan yetkilendirmesi journal'a yazılan motor durumudur ve yeniden başlatmalardan sonra korunur
• Bu uç nokta üzerinden yapılan onayların süresi dolmaz

Ajan Yetkisini Kaldırma

Uç nokta: 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 yapısı:

struct RevokeAgent {
    address agent;
    uint64 nonce;
}

Yanıt: RevokeAgentResponse

Notlar:

• Motorun sahip olduğu yetkilendirme durumuna journal'a yazılan bir RevokeAgent komutu uygular
• İşlem API'si yetkilendirme kontrolleri arka uç durumunu okur ve işlem istekleri için yetki kaldırmalarını uygular. Trollbox gönderimi, olumlu ajan yetkilendirmesini daha uzun süre önbellekte tutabilir; bu nedenle yetkisi yakın zamanda kaldırılmış bir ajan, bu önbelleğin süresi dolana veya en iyi çaba esaslı geçersiz kılma ilgili edge konumuna ulaşana kadar gönderi yapabilmeye devam edebilir. Bu önbellek, işlem API'si değişikliklerini yetkilendirmez.
• Yetki kaldırıldıktan sonra ajan artık cüzdan adına imzalayamaz

Tüm Ajanların Yetkisini Kaldırma

Uç nokta: DELETE /revoke-all-agents

İstek: { "nonce": 3, "signature": "0x..." }, cüzdan sahibi tarafından RevokeAllAgents(uint64 nonce) üzerinden imzalanır. Kurtarılan cüzdana ait tüm ajanları kaldırır.

Yetkili Ajanları Getirme

Uç nokta: GET /authorized-agents?wallet=...

Sorgu parametreleri:

• wallet (zorunlu)

Yanıt:

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

Notlar:

• Yalnızca aktif ve süresi dolmamış ajanları döndürür

Ajan Kullanımı

Ajan ile Emir İmzalama

Bir ajan onaylandıktan sonra:

1. Emri ajan cüzdanıyla imzalayın: PlaceOrder / CancelOrder mesajlarını imzalamak için ajan cüzdanını kullanın
2. Cüzdan alanını ayarlayın: wallet alanını işlem cüzdanı adresine ayarlayın (ajan adresine değil)
3. Middleware doğrulaması: Middleware, ajanı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. The REST body uses snake_case `client_id`.
const { clientId, ...rest } = message;
const response = await fetch('/order', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ...rest,
    client_id: clientId,
    signature
  })
});

Ajan ile Toplu Emirler

Toplu uç noktalar, ajan yetkilendirmesini her öğe için ayrı ayrı doğrular:

• POST /bulk_order içindeki her emir farklı bir ajan tarafından imzalanabilir
• Ajan yetkilendirmesi her öğe için ayrı kontrol edilir
• Herhangi bir öğe ajan yetkilendirmesinden geçemezse, o öğe BulkOrderResult içinde hata döndürür

Yetkilendirme Kontrolleri

Middleware (Tekil Emirler)

Uç noktalar:

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

Kontrol: signature_and_agent_middleware şunları doğrular:

1. İmza kurtarma başarılıdır
2. İmzalayan yetkilidir (signer == wallet VEYA ajan yetkili)

Handler (Toplu Emirler)

Uç noktalar:

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

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

1. Her öğe için imza kurtarma
2. Her öğe için ajan yetkilendirme kontrolü

Yetkilendirme Depolaması

Ajan yetkilendirmesi, motorun sahip olduğu durumdur. ApproveAgent ve RevokeAgent komutları journal'a yazılır, motor replay'i ile geri yüklenir ve API kontrolleri için okuma snapshot'ı üzerinden sunulur.

Yetkilendirme Mantığı

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

• Doğrudan imzalama: signer == wallet.
• Ajan ile imzalama: motor snapshot'ı wallet_address == <wallet> ve agent_address == <signer> için bir yetkilendirme kaydı içerir ve expires_at ya yoktur ya da gelecekte bir zamandır.

Süre Sonu

Motor, bir yetkilendirme üzerinde expires_at alanını destekler ve süresi dolmuş bir ajanı yetkisiz kabul eder. POST /approve-agent bu alanı ayarlamaz; bu nedenle API üzerinden onaylanan ajanlar, yetkileri kaldırılana kadar aktif kalır.

Güvenlik Hususları

1. Ajan anahtarı güvenliği: Ajan özel anahtarlarını koruyun (donanım cüzdanları veya güvenli anahtar yönetimi kullanın)
2. Düzenli denetimler: Yetkili ajanları GET /authorized-agents ile düzenli olarak gözden geçirin
3. Kullanılmayan ajanların yetkisini kaldırın: Artık ihtiyaç duyulmayan ajanların yetkisini kaldırın

En İyi Uygulamalar

1. Otomasyon için ajan kullanın: İşlem cüzdanı anahtarlarını soğuk depolamada tutun, otomatik sistemler için ajan kullanın
2. Ajan kapsamını sınırlayın: Yalnızca erişime ihtiyaç duyan ajanları onaylayın
3. Ajan kullanımını izleyin: Hangi ajanların emir verdiğini takip edin
4. Yetkiyi derhal kaldırın: Artık ihtiyaç duyulmayan ajanların yetkisini hemen kaldırın

Sık Karşılaşılan Sorunlar

"Signer 0x... is not authorized to act for wallet 0x..."

Neden: Ajan onaylanmamış veya yetkilendirmenin süresi dolmuş/yetki kaldırılmış.

Çözüm: Ajanı POST /approve-agent ile onaylayın veya doğrudan cüzdanla imzalayın.

Ajan Yetkilendirmesi Çalışmıyor

Nedenler:

• Ajan, motorun sahip olduğu yetkilendirme durumunda bulunmuyor
• Yetkilendirme kaldırılmış
• Yetkilendirmenin süresi dolmuş

Çözüm: Ajan durumunu GET /authorized-agents?wallet=... ile kontrol edin.