x402 ile Başlarken

x402 protokolü (L402 olarak da bilinir), abonelik gerektirmeden kullanım başına ödeme ile erişim sağlayan API para kazanma için ortaya çıkan bir standarttır.

Minara x402 uç noktası: https://x402.minara.ai

x402 nedir?

x402, web için yerel bir "öde-oyna" sistemidir. Abonelik için ön ödeme yapmak yerine, her API çağrısı için $USDC gibi stabilcoinlerle doğrudan ödeme yaparsınız.

Temel Faydalar:

• Abonelik Gerekmez: Sadece kullandığınız için ödeyin

• İzin Gerektirmeyen Erişim: Hesap oluşturma veya onay süreci yok

• Anında Aktivasyon: Ödemeden hemen sonra API'leri kullanmaya başlayın

• Kripto-yerel: Base, Solana veya Polygon üzerinde USDC ile ödemeler

• Şeffaf Fiyatlandırma: Her API çağrısının maliyetini tam olarak bilin

Nasıl çalışır:

x402 protokolü, şu anahtar adımlarla bir ödeme-zorlama akışını izler:

Tam Akış

1. İlk İstek (İstemci → Sunucu)

   • Ödeme yapmadan korumalı bir uç noktaya API isteği yaparsınız

2. Ödeme Zorluğu (Sunucu → İstemci)

   • Sunucu şu şekilde yanıt verir 402 Ödeme Gerekli durum

   • Ödeme talimatlarını döndürür (tutar, para birimi, alıcı adresi, zincir)

3. Ödeme Seçimi (İstemci)

   • Bir ödeme yöntemi seçer ve bir ödeme yükü oluşturursunuz

   • Belirtilen zincirde USDC ile ödemeye hazırlan

4. Kimlik Doğrulanmış İstek (İstemci → Sunucu)

   • Ödeme kanıtını şuraya dahil edin x-payment-response başlık

   • Orijinal isteği yeniden dene

5. Doğrulama (Sunucu → Kolaylaştırıcı)

   • Sunucu doğrulama için ödeme kanıtını kolaylaştırıcıya gönderir

   • Ödemenin geçerliliğini onaylar

6. Ödeme İşleme (Kolaylaştırıcı → Blokzincir)

   • Kolaylaştırıcı işlemi blokzincire gönderir

   • İşlem zincir üzerinde onaylanır

7. Mutabakat (Kolaylaştırıcı → Sunucu)

   • Kolaylaştırıcı sunucuya mutabakatı onaylar

   • Ödeme tamamlanır

8. Erişim Verildi (Sunucu → İstemci)

   • API yanıtını alırsınız

   • Ödeme makbuzu şurada dahil edilir X-PAYMENT-RESPONSE başlık

Ana Bileşenler

• İstemci: API istekleri yapan uygulamanız

• Sunucu: Minara API uç noktaları (https://x402.minara.ai)

• Kolaylaştırıcı: Ödeme doğrulama ve mutabakat hizmeti

• Blokzincir: Zincir üstü ödeme mutabakatı (Base, Solana veya Polygon)

---

x402'yi Minara ile Nasıl Kullanırsınız

1. x402 SDK'sını Kullanma (Önerilen)

Çoğu geliştirici, tüm ödeme akışlarını otomatik olarak yöneten resmi x402 SDK'sını kullanır.

Siz sadece istek yaparsınız: SDK ödeme zorluklarını, doğrulamayı ve mutabakatı sizin için yönetir.

Ön Koşullar

Başlamadan önce sahip olduğunuzdan emin olun:

• USDC bulunan bir kripto cüzdanı (herhangi bir EVM-uyumlu cüzdan)

• Node.js ve npm, Go veya Python ve pip

• Ödemeleri imzalamak için cüzdanınızın özel anahtarı

Adım 1: Bağımlılıkları Kurun

Node.js / TypeScript

# Fetch tabanlı istemciler için (önerilir)
npm install @x402/fetch @x402/evm

# Axios tabanlı istemciler için
npm install @x402/axios @x402/evm

# Solana desteği için ayrıca ekleyin:
npm install @x402/svm

Python

# httpx (async) için - önerilir
pip install "x402[httpx]"

# requests (sync) için
pip install "x402[requests]"

# Solana desteği için ayrıca ekleyin:
pip install "x402[svm]"

Go

go get github.com/coinbase/x402/go

Adım 2: Cüzdan İmzacı (Signer) Ayarlayın

Node.js (viem kullanarak)

npm install viem

import { privateKeyToAccount } from "viem/accounts";

// Özel anahtardan bir imzacı oluşturun (çevresel değişken kullanın)
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

Solana için:

import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

const svmSigner = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SOLANA_PRIVATE_KEY!)
);

Python (eth-account kullanarak)

pip install eth_account

import os
from eth_account import Account
from x402.mechanisms.evm import EthAccountSigner

account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
signer = EthAccountSigner(account)

Go

import (
    evmsigners "github.com/coinbase/x402/go/signers/evm"
)

evmSigner, err := evmsigners.NewClientSignerFromPrivateKey(os.Getenv("EVM_PRIVATE_KEY"))
if err != nil {
    log.Fatal(err)
}

Adım 3: İstek Yapın: Ödemeler Otomatik Olarak Yönetilir!

SDK ödeme zorluklarını otomatik olarak sizin için yönetir. Sadece normal şekilde istek yapın!

Node.js (fetch ile)

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

// İmzacı oluştur
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

// x402 istemcisi oluştur ve EVM şemasını kaydet
const client = new x402Client();
registerExactEvmScheme(client, { signer });

// Fetch'i ödeme yönetimi ile sar
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// İstek yap - ödeme otomatik olarak yönetilir! 🎉
const response = await fetchWithPayment("https://x402.minara.ai/x402/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    userQuery: "BTC'nin mevcut fiyatı nedir?"
  })
});

const data = await response.json();
console.log("Response:", data.content);

// Ödeme makbuzunu al (isteğe bağlı)
if (response.ok) {
  const httpClient = new x402HTTPClient(client);
  const paymentResponse = httpClient.getPaymentSettleResponse(
    (name) => response.headers.get(name)
  );
  console.log("Payment settled:", paymentResponse);
}

📖 Tam örnek GitHub'da

Node.js (axios ile)

import { x402Client, wrapAxiosWithPayment } from "@x402/axios";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import axios from "axios";

// İmzacı oluştur
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

// x402 istemcisi oluştur ve EVM şemasını kaydet
const client = new x402Client();
registerExactEvmScheme(client, { signer });

// Ödeme yönetimi ile bir Axios örneği oluştur
const api = wrapAxiosWithPayment(
  axios.create({ baseURL: "https://x402.minara.ai" }),
  client
);

// İstek yap - ödeme otomatik olarak yönetilir! 🎉
const response = await api.post("/x402/chat", {
  userQuery: "ETH fiyat hareketini analiz et"
});

console.log("Response:", response.data.content);

📖 Tam örnek GitHub'da

Python (httpx ile async)

import asyncio
import os
from eth_account import Account

from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client


async def call_minara():
    # İstemci oluştur ve EVM şemasını kaydet
    client = x402Client()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    # İstek yap - ödeme otomatik olarak yönetilir! 🎉
    async with x402HttpxClient(client) as http:
        response = await http.post(
            "https://x402.minara.ai/x402/chat",
            json={"userQuery": "BTC fiyatı nedir?"}
        )
        await response.aread()
        
        data = response.json()
        print(f"Response: {data['content']}")


asyncio.run(call_minara())

📖 Tam örnek GitHub'da

Python (requests ile sync)

import os
from eth_account import Account

from x402 import x402ClientSync
from x402.http.clients import x402_requests
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client


def call_minara():
    # İstemci oluştur ve EVM şemasını kaydet
    client = x402ClientSync()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    # İstek yap - ödeme otomatik olarak yönetilir! 🎉
    with x402_requests(client) as session:
        response = session.post(
            "https://x402.minara.ai/x402/chat",
            json={"userQuery": "BTC fiyatı nedir?"}
        )
        
        data = response.json()
        print(f"Response: {data['content']}")


call_minara()

📖 Tam örnek GitHub'da

Go

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
    "time"

    x402 "github.com/coinbase/x402/go"
    x402http "github.com/coinbase/x402/go/http"
    evm "github.com/coinbase/x402/go/mechanisms/evm/exact/client"
    evmsigners "github.com/coinbase/x402/go/signers/evm"
)

func main() {
    // EVM imzacısı oluştur
    evmSigner, _ := evmsigners.NewClientSignerFromPrivateKey(os.Getenv("EVM_PRIVATE_KEY"))

    // x402 istemcisi oluştur ve EVM şemasını kaydet
    x402Client := x402.Newx402Client().
        Register("eip155:*", evm.NewExactEvmScheme(evmSigner))

    // HTTP istemcisini ödeme yönetimi ile sar
    httpClient := x402http.WrapHTTPClientWithPayment(
        http.DefaultClient,
        x402http.Newx402HTTPClient(x402Client),
    )

    // İstek gövdesini hazırla
    reqBody := map[string]string{"userQuery": "BTC fiyatı nedir?"}
    jsonData, _ := json.Marshal(reqBody)

    // İstek yap - ödeme otomatik olarak yönetilir! 🎉
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    req, _ := http.NewRequestWithContext(ctx, "POST", "https://x402.minara.ai/x402/chat", bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    
    resp, err := httpClient.Do(req)
    if err != nil {
        fmt.Printf("Request failed: %v\n", err)
        return
    }
    defer resp.Body.Close()

    var data map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&data)
    fmt.Printf("Response: %v\n", data["content"])
}

📖 Tam örnek GitHub'da

Çok Zincirli Destek (Base + Solana + Polygon)

Tüm Minara zincirlerini desteklemek için birden çok ödeme şeması kaydedebilirsiniz:

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { registerExactSvmScheme } from "@x402/svm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

// Farklı zincirler için imzacılar oluştur
const evmSigner = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const svmSigner = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SOLANA_PRIVATE_KEY!)
);

// Birden çok şemayla istemci oluştur
const client = new x402Client();
registerExactEvmScheme(client, { signer: evmSigner });  // Base + Polygon
registerExactSvmScheme(client, { signer: svmSigner });  // Solana

const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// Artık HERHANGİ bir Minara uç noktasını çağırabilirsiniz! 🚀
// Base uç noktaları
await fetchWithPayment("https://x402.minara.ai/x402/chat", {...});

// Solana uç noktaları  
await fetchWithPayment("https://x402.minara.ai/x402/solana/chat", {...});

// Polygon uç noktaları
await fetchWithPayment("https://x402.minara.ai/x402/polygon/chat", {...});

Tam Örnek: Minara ile Sohbet

İşte Minara'nın AI sohbet uç noktasını çağıran tam çalışan bir örnek:

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client, x402HTTPClient } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

async function chatWithMinara(query: string) {
  // 1. İmzacıyı ayarla
  const signer = privateKeyToAccount(
    process.env.EVM_PRIVATE_KEY as `0x${string}`
  );

  // 2. x402 istemcisini oluştur
  const client = new x402Client();
  registerExactEvmScheme(client, { signer });

  // 3. Fetch'i sar
  const fetchWithPayment = wrapFetchWithPayment(fetch, client);

  // 4. İstek yap - SDK ödemeyi otomatik olarak yönetir!
  const response = await fetchWithPayment("https://x402.minara.ai/x402/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ userQuery: query })
  });

  const data = await response.json();
  return data.content;
}

// Kullanım
const answer = await chatWithMinara("BTC'nin mevcut fiyatı nedir?");
console.log(answer);
// Çıktı: "BTC şu anda $98,450 seviyesinde işlem görüyor. Ana destek seviyeleri..."

Daha fazla bilgi için lütfen resmi x402 belgelerine bakın: Alıcılar için Hızlı Başlangıç

---

2. Manuel Ödeme Akışı (SDK Olmadan)

SDK kullanmak istemiyorsanız, ödemeleri manuel olarak yönetebilirsiniz:

Adım 1: İlk İsteği Yapın

curl -X POST https://x402.minara.ai/x402/chat \
  -H "Content-Type: application/json" \
  -d '{"userQuery": "BTC fiyatı nedir?"}'

Adım 2: Ödeme Zorluğunu Alın

{
  "error": "payment_required",
  "message": "Bu kaynağa erişmek için ödeme gereklidir",
  "paymentInstructions": {
    "amount": "0.20",
    "currency": "USDC",
    "recipient": "0xCF5815e9063FA0b04Be0Cb5C1DB583eeF9ef5fbB",
    "chain": "base"
  }
}

Adım 3: Cüzdanla Ödeyin

MetaMask, Phantom veya herhangi bir Web3 cüzdanını kullanarak USDC'yi alıcı adresine gönderin.

Adım 4: Ödeme Kanıtı ile Yeniden Dene

curl -X POST https://x402.minara.ai/x402/chat \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{"userQuery": "BTC fiyatı nedir?"}'

Adım 5: Yanıtı Alın

{
  "content": "BTC şu anda $98,450 seviyesinde işlem görüyor..."
}

---

Hata Yönetimi

Minara API'sinden Yaygın Hatalar

402 Ödeme Gerekli

{ "error": "payment_required" }

→ Normal! SDK bunu otomatik olarak yönetecektir.

401 Yetkisiz

{ "error": "unauthorized", "message": "Geçersiz ödeme yanıtı belirteci" }

→ Ödeme kanıtı geçersiz veya süresi dolmuş. SDK yeniden deneyecektir.

400 Geçersiz İstek

{ "error": "bad_request", "message": "Gerekli parametre eksik: userQuery" }

→ İstek gövdesinin gerekli alanları içerdiğini kontrol edin.

Hız Sınırları

x402 uç noktaları cüzdan adresi başına hız sınırlıdır:

• AI Uç Noktaları: 60 istek/dakika

• Ticaret Uç Noktaları: 30 istek/dakika

Limitleri aşarsanız:

{
  "error": "rate_limit_exceeded",
  "message": "Çok fazla istek. Lütfen 30 saniye sonra tekrar deneyin.",
  "retryAfter": 30
}

---

Kaynaklar & Destek

📚 Resmi x402 Kaynakları

• x402 Protokol Belgeleri

• Alıcılar için Hızlı Başlangıç

• x402 GitHub Deposu

• x402 Discord

📦 NPM Paketleri

• @x402/fetch - Fetch sarmalayıcı

• @x402/axios - Axios kesici (interceptor)

• @x402/evm - EVM desteği (Base, Polygon)

• @x402/svm - Solana desteği

• x402 Python Paketi

🔍 Minara'ya Özgü

• x402scan'de Minara - Tüm uç noktaları görüntüle

• Minara API Referansı (x402) - API Referansı (x402)

API Referansı

API Referansı (x402)