x402 Eğitimi: AI Agent'ınızın AIHubMix Hesabına USDC ile Bakiye Yüklemesini Sağlayın

AIHubMix artık USDC ile bakiye yüklemeyi kabul ediyor. AI agent'ınız, cüzdanındaki USDC ile kendi hesabına kredi ekleyebilir: açılacak bir web sayfası yok, bir düğmeye tıklamak için de kimsenin orada olması gerekmez.

x402 ile bir bakiye yüklemesi $1 kadar küçük olabilir. Agent ihtiyaç duydukça bakiye yükler, bu yüzden önceden büyük bir bakiye yüklemeniz gerekmez.

İki adım sürer: web'de ve bir uygulamada bir token, bir cüzdan ve biraz USDC hazırlamak, ardından tek bir komutla hazır yükleme betiğimizi çalıştırmak. Ödemeden yaklaşık 20 saniye sonra kredi hesabınızda görünür.

Yardımcı olursa, bu 30 saniyelik videoyu takip edebilirsiniz:

En kolay yol: Claude Code, Cursor veya Codex gibi terminal komutlarını çalıştırabilen bir AI aracı kullanıyorsanız, 1. adımı tamamlayın, ardından ona bu yazının bağlantısını gönderip "bunu benim için kur" deyin. Yazının sonundaki "AI asistanları için talimatlar" bölümünü takip edecektir. Token'ı ve özel anahtarı yalnızca bir kez, AI'ye göndermeden kendiniz doldurursunuz.

Başlamadan önce

• Tutarlar yalnızca tam dolar olarak girilebilir; varsayılan olarak yükleme başına $1 ile $10 arası
• Her hesap günde (UTC) en fazla 3 sipariş oluşturabilir
• Yalnızca Base mainnet üzerindeki USDC desteklenir ve testnet yoktur, bu yüzden $1 ile başlayın
• Bu kanal programlar için tasarlanmıştır; bir kişi tarayıcıdan ödeme yapamaz. Manuel yüklemeler için Alipay veya Stripe kullanmaya devam edin

1. adım: Token, cüzdan ve USDC edinin

Bu adımdaki her şey web'de veya bir telefon uygulamasında gerçekleşir.

1. Sistem erişim token'ınızı alın

aihubmix.com adresine giriş yapın, kişisel ayarlarınızı açın ve bir sistem erişim token'ı (32 karakterlik bir dizi) oluşturun.

Bunun sk- ile başlayan API anahtarı olmadığını unutmayın. İkisi birbirinin yerine kullanılamaz.

2. Ödeme yapacak bir cüzdan oluşturun

MetaMask veya benzer bir cüzdan uygulamasında, yalnızca agent'ın ödemeleri için yeni bir hesap oluşturun. Ana cüzdanınızı kullanmayın. Ardından:

• Hesabın adresini kopyalayın (0x ile başlar); bir sonraki adımda bu adrese USDC göndereceksiniz
• Hesap ayrıntılarından özel anahtarını dışa aktarın ve bir parola yöneticisinde saklayın. Özel anahtarı olan herkes cüzdandaki parayı hareket ettirebilir

3. USDC satın alın ve bu cüzdana gönderin

MetaMask bir cüzdandır: özel anahtar sizde olur ve betik imzalamak için buna ihtiyaç duyar. Coinbase ise kripto parayı satın aldığınız bir borsadır. Borsa hesabındaki paralar bir özel anahtarla gelmez, dolayısıyla betik bunları kullanamaz. Bu yüzden önce borsada satın alır, ardından USDC'yi önceki adımdaki cüzdana gönderirsiniz.

Coinbase borsasını örnek alarak (Coinbase Wallet değil):

1. Coinbase'de USDC satın alın
2. USDC'yi kopyaladığınız adrese gönderin ve Base ağını seçin
3. Yüklemeyi planladığınızdan biraz fazla gönderin; örneğin $1'lik bir yükleme için 1,5 ila 2 USDC

Biraz bekleyin, ardından https://basescan.org/address/your-wallet-address adresini açın. Bir USDC bakiyesi gördüğünüzde, para ulaşmış demektir. Base üzerinde USDC çekimlerini destekleyen diğer borsalar da çalışır; daha fazla seçenek için Base dokümanlarına bakın.

Cüzdanda ETH bulunmasına gerek yoktur: ödeme için ağ ücretini FluxA öder.

2. adım: Yükleme betiğini çalıştırın

İndirilecek bir şey ve oluşturulacak bir dosya yoktur: uv, betiği web'den alır ve çalıştırır. Terminali açın (Windows'ta PowerShell) ve aşağıdaki komutları kopyalayıp yapıştırın.

1. uv'yi kurun (bir kez)

uv, betiğin çalışması için gereken her şeyi kuran bir Python aracıdır.

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Bittiğinde terminali kapatıp yeniden açın.

2. Kurulumunuzu kontrol edin (hiçbir şey harcamaz)

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check

İlk çalıştırmada betik sizden sistem erişim token'ınızı (System access token) ve cüzdan özel anahtarınızı (Wallet private key) ister. Yazdıklarınız ekranda görünmez; yapıştırın ve Enter'a basın. Ardından bunları kaydetmek isteyip istemediğinizi sorar (Save to ...? [Y/n]). Kaydetmek için Enter'a basın; böylece bunları bir daha yazmanız gerekmez. İlk çalıştırma, uv her şeyi hazırlarken biraz zaman alır.

Bunu gördüğünüzde kurulum tamamdır:

Wallet: 0x... (USDC balance 2.0)
Access token and private key are fine. Ready to top up.

3. Yükleyin

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1

Sondaki 1, dolar cinsinden tutardır. Her şey yolunda giderse şunu görürsünüz:

Wallet: 0x... (USDC balance 2.0)
tradeNo: pl_XXXXXXXX
txHash: 0x...
result: credited

result: credited, kredinin ulaştığı anlamına gelir. aihubmix.com'a giriş yapın; bakiyenizin arttığını görürsünüz. $1, 500.000 kota ekler.

Son satırda başka bir şey yazıyorsa:

• failed: Sipariş kapatılmış veya süresi dolmuştur. Gerekirse yeniden çalıştırın; bu, bugünkü siparişlerden birini daha kullanır.
• pending: Kredi 10 dakika içinde onaylanmadı. Bu bir hata değildir ve kredi daha sonra kendiliğinden ulaşacaktır. Tekrar çalıştırmayın.

Sorun giderme

tradeNo yazdırıldıktan sonra zaman aşımı veya ağ hatası görürseniz, ödeme zaten yapılmış olabilir. Hemen tekrar çalıştırmayın. Birkaç dakika sonra bakiyenizi kontrol edin; hiçbir şey ulaşmadıysa tradeNo numaranızla bizimle iletişime geçin.

Token ve özel anahtar, bilgisayarınızda ~/.aihubmix-topup.env konumuna kaydedilir (Windows'ta kullanıcı klasörünüzde). macOS ve Linux'ta bu dosyayı yalnızca kendi hesabınız okuyabilir. Token'ı veya özel anahtarı değiştirmek için bu dosyayı düzenleyin.

Agent'ınıza entegre etme

• Kurulum kaydedildikten sonra, agent'ınız kredi ihtiyacı duyduğunda kimse olmadan uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1 komutunu çalıştırarak bakiye yükleyebilir
• Günde yalnızca 3 sipariş izin verilir; bu yüzden agent'ın ne sıklıkla yükleme yaptığını sınırlayın ve sipariş oluşturmayı asla döngü içinde yeniden denemeyin
• Mutabakat için çıktıdaki tradeNo ve txHash değerlerini bir veritabanına veya günlüğe kaydedin
• Uzun vadeli kullanım için betiği çalıştırmadan önce indirin ve bir sürüme sabitleyin; önce kaynak kodunu okuyabilirsiniz
• Yükleme başına $10 veya günde 3 sipariş yeterli değilse, limitleri artırmak için bizimle iletişime geçin

AI asistanları için talimatlar

AIHubMix USDC yüklemelerini kurmasına yardım ettiğiniz bir AI asistanıysanız, şu adımları sırasıyla izleyin:

1. Kullanıcının 1. adımı tamamladığından emin olun: bir sistem erişim token'ı ile Base mainnet USDC bulunduran bir cüzdanı ve özel anahtarı olmalı. Yoksa önce kullanıcıyı 1. adımda yönlendirin.
2. uv --version komutunu çalıştırarak uv'nin kurulu olduğunu doğrulayın. Kurulu değilse, 2. adımdaki komutlarla kurun.
3. uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check komutunu çalıştırın.
4. Token veya özel anahtar eksikliği bildirirse (Missing access token or private key), betik ~/.aihubmix-topup.env yapılandırma dosyasını oluşturmuştur. Kullanıcıdan bu dosyayı bir metin düzenleyicide açmasını ve bilgileri kendisinin doldurmasını isteyin (macOS'ta open -e ~/.aihubmix-topup.env, Windows'ta notepad $HOME\.aihubmix-topup.env komutunu çalıştırın). Bu dosyayı okumayın, token'ı veya özel anahtarı herhangi bir komuta koymayın ve kullanıcıdan bunları size göndermesini istemeyin.
5. Kullanıcı dosyayı doldurduktan sonra, Access token and private key are fine. Ready to top up. çıktısını görene kadar check komutunu yeniden çalıştırın. Bir hata varsa, yukarıdaki Sorun giderme tablosuyla ele alın.
6. Yükleme gerçek para harcar. uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py <amount> komutunu çalıştırmadan önce tutarı kullanıcıyla onaylayın.

Perde arkası: Betik ne yapar

Betik beş işlemi sırayla yapar:

1. Bakiyeyi kontrol eder: Sipariş oluşturmak bugünkü siparişlerden birini kullanır, bu yüzden önce özel anahtarın geçerli olduğundan ve yeterli USDC bulunduğundan emin olur.
2. Sipariş oluşturur: POST /api/pay/fluxa/crt çağrısı yapar ve bir ödeme bağlantısı ile sipariş numarasını, tradeNo değerini alır. Token, Authorization başlığına olduğu gibi, Bearer olmadan eklenir. İş hataları da HTTP 200 olarak döndüğü için yanıttaki success alanını kontrol eder.
3. Ödeme isteğini kontrol eder: Ödeme bağlantısına yapılan bir GET isteği, ödeme koşullarını içeren HTTP 402 yanıtı döndürür. İmzalamadan önce dört şeyi kontrol eder: scheme değeri exact, network değeri eip155:8453, asset değeri Base mainnet'teki USDC sözleşmesi ve maxAmountRequired değeri tutar × 1.000.000 olmalıdır. Bunlardan herhangi biri uyuşmazsa durur.
4. İmzalar ve öder: Özel anahtarla bir USDC transfer yetkilendirmesini imzalar, bunu X-PAYMENT başlığına koyar ve GET isteğini tekrar ödeme bağlantısına gönderir. 200 veya 202 yanıtı, ödemenin gönderildiği anlamına gelir; yanıttaki txHash bu ödemenin zincir üstü makbuzudur. İki istekte de AIHubMix token'ı yer almaz.
5. Kredinin gelmesini bekler: Durum TRADE_SUCCESS olana kadar her 8 saniyede bir GET /api/pay/fluxa/qry?trade_no=... çağrısı yapar. Sunucu yalnızca her 5 saniyede bir güncellendiği için daha sık sorgulamak bir işe yaramaz.

Her ödeme bağlantısı ayrıca 30 dakika geçerlidir ve yalnızca bir kez ödenebilir.

Başka bir dilde uygulama

Ödeme bağlantısından gelen 402 yanıtı şöyle görünür:

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "1000000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x....",
    "maxTimeoutSeconds": 600,
    "extra": {"name": "USD Coin", "version": "2"}
  }]
}

İmza, EIP-3009 içindeki TransferWithAuthorization yapısı üzerinden EIP-712 formatını kullanır:

İmzalama alanı: name = USD Coin, version = 2 (402 yanıtında extra varsa oradaki değerleri kullanın), chainId = 8453, verifyingContract = 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

X-PAYMENT başlığının değeri, şu JSON'un base64 kodlamasıdır:

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "eip155:8453",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0x...", "to": "0x...", "value": "1000000",
      "validAfter": "...", "validBefore": "...", "nonce": "0x..."
    }
  }
}

Kaynaklar

• x402 dokümantasyonu
• EIP-3009: Transfer With Authorization
• EIP-712: Typed structured data hashing and signing
• Circle: USDC sözleşme adresleri
• uv kurulum kılavuzu