X402

يتيح لك X402 استخدام مسارات Venice API المدفوعة عن طريق المصادقة بمحفظة والاحتفاظ برصيد USDC مدفوع مسبقًا. لا حاجة إلى مفتاح API أو حساب. وقّع رسالة، واشحن الرصيد على Base أو Solana، واستدعِ أي مسار مدعوم.

مصادقة المحفظة

صادِق باستخدام حمولة Sign-In-With-X موقّعة في ترويسة X-Sign-In-With-X.

ادفع بـ USDC

احتفظ برصيد قابل للإنفاق باستخدام USDC على Base أو Solana.

DIEM أولًا

إذا كانت المحفظة مرتبطة بحساب Venice يمتلك رصيد DIEM، فيُنفَق ذلك أولًا.

ما هو X402؟

X402 هو معيار دفع مفتوح يسمح للتطبيقات والوكلاء بالدفع مقابل الخدمات برمجيًا باستخدام العملة المشفّرة. تدعم Venice X402 بحيث يمكن للمحافظ المصادقة والدفع مقابل الاستدلال مباشرة بـ USDC على Base أو Solana.

المتطلبات المسبقة

محفظة على Base أو Solana
عملة أصلية للغاز على السلسلة المختارة، مثل ETH على Base أو SOL على Solana
USDC على السلسلة المختارة (أو رصيد مدعوم بـ DIEM قائم من حساب Venice مرتبط)

فكّر في استخدام محفظة مخصّصة للأتمتة بدلًا من محفظة الخزينة الرئيسية.

البدء السريع

يوفّر SDK venice-x402-client أدوات مساعدة لمصادقة المحفظة وشحن الرصيد وتتبّع الرصيد.

npm install venice-x402-client

import { VeniceClient } from 'venice-x402-client'

const venice = new VeniceClient(process.env.WALLET_KEY)

await venice.topUp(10) // تجاوزه إذا كانت المحفظة تمتلك رصيدًا قابلًا للإنفاق بالفعل

const response = await venice.chat({
  model: 'kimi-k2-5',
  messages: [{ role: 'user', content: 'Hello!' }]
})

يولّد العميل ترويسة X-Sign-In-With-X جديدة لكل طلب ويتتبّع الرصيد تلقائيًا من ترويسات الاستجابة X-Balance-Remaining.

مع الأدوات المتوافقة مع OpenAI

إذا كنت تستخدم أداة تقبل fetch مخصّصًا، استخدم createAuthFetch لإضافة مصادقة المحفظة إلى أي طلب:

import { createAuthFetch } from 'venice-x402-client'

const authFetch = createAuthFetch(process.env.WALLET_KEY)

الأدوات المساعدة المتاحة

يتضمّن الـ SDK أدوات مساعدة من الدرجة الأولى لأكثر مسارات Venice x402 شيوعًا. لما هو غير مغطّى، استخدم request() أو createAuthFetch() مباشرة.

الفئة	الدوال
Chat	`chat()`, `chatStream()`
Responses	`responses.create()`, `responses.stream()`
Images	`images.generate()`, `images.generations()`, `images.upscale()`, `images.edit()`, `images.multiEdit()`, `images.backgroundRemove()`
Audio	`audio.speech()`, `audio.transcribe()`, `audio.queue()`, `audio.retrieve()`, `audio.complete()`
Video	`video.queue()`, `video.retrieve()`, `video.generate()`, `video.complete()`, `video.transcribe()`
Embeddings	`embeddings()`
Models	`models()`
Wallet	`getBalance()`, `getTransactions()`, `topUp()`

التدفّق اليدوي

إذا كنت لا تستخدم الـ SDK أو تحتاج إلى فهم البروتوكول الأساسي، فإليك التدفّق خطوة بخطوة. لمحفظة جديدة، افترض أنك تحتاج إلى شحن الرصيد أولًا ما لم تكن تمتلك بالفعل رصيد DIEM قابلًا للإنفاق. تتوقّع Venice حمولة JSON مشفّرة بـ Base64 تحتوي على رسالة Sign-In-With-X موقّعة. توقّع محافظ EVM رسالة SIWE وفق EIP-4361 على Base. وتوقّع محافظ Solana رسالة SIWX الخاصة بـ Solana بـ Ed25519. أنشئ nonce وطابعًا زمنيًا جديدين لكل تدفّق طلب. بالنسبة لـ Solana، اضبط chainId على solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp، وضمّن type: "ed25519" في حمولة JSON المشفّرة، وقدّم توقيع Ed25519 كـ base58 أو base64. تبدأ الرسالة الموقّعة بـ <domain> wants you to sign in with your Solana account:، يتبعها عنوان المحفظة والحقول القياسية URI وVersion وChain ID وNonce وIssued At وExpiration Time الاختياري.

import { Wallet } from 'ethers'
import { SiweMessage, generateNonce } from 'siwe'

const wallet = new Wallet(process.env.EVM_PRIVATE_KEY)
const now = new Date()
const resourceUrl = 'https://api.venice.ai/api/v1/chat/completions'

const siwe = new SiweMessage({
  domain: 'api.venice.ai',
  address: wallet.address,
  statement: 'Sign in to Venice AI',
  uri: resourceUrl,
  version: '1',
  chainId: 8453,
  nonce: generateNonce(),
  issuedAt: now.toISOString(),
  expirationTime: new Date(now.getTime() + 5 * 60 * 1000).toISOString(),
})

const message = siwe.prepareMessage()
const signature = await wallet.signMessage(message)

const xSignInWithX = Buffer.from(
  JSON.stringify({
    address: wallet.address,
    message,
    signature,
    timestamp: now.getTime(),
    chainId: 8453,
  }),
  'utf8',
).toString('base64')

console.log(xSignInWithX)

الخطوة 2: التحقق من الرصيد

قبل إجراء طلب مدفوع، تحقّق من أن المحفظة تمتلك رصيدًا قابلًا للإنفاق:

export WALLET_ADDRESS=0xYOUR_WALLET_ADDRESS_OR_SOLANA_ADDRESS
export X402_AUTH=YOUR_BASE64_SIWX_HEADER

curl --request GET \
  --url "https://api.venice.ai/api/v1/x402/balance/$WALLET_ADDRESS" \
  --header "X-Sign-In-With-X: $X402_AUTH"

تتضمّن الاستجابة:

canConsume: ما إذا كانت المحفظة قادرة على إجراء طلبات مدفوعة
balanceUsd: الرصيد القابل للإنفاق الحالي
minimumTopUpUsd وsuggestedTopUpUsd: إرشادات لشحن الرصيد
diemBalanceUsd: الرصيد المدعوم بـ DIEM، إن وُجد

يقبل معامل المسار walletAddress إما عنوان EVM (0x...) أو عنوان Solana بصيغة base58.

الخطوة 3: شحن الرصيد

اشحن باستخدام USDC على Base أو Solana:

curl --request POST \
  --url https://api.venice.ai/api/v1/x402/top-up

تُرجع المكالمة الأولى 402 Payment Required مع ترويسة PAYMENT-REQUIRED تحتوي على مصفوفة accepts. كل عنصر يصف خيار دفع مقبولًا واحدًا، بما في ذلك network وasset وpayTo وamount. اختر خيار Base أو Solana الذي تريد الدفع به، واستخدم تلك التفاصيل الدقيقة لبناء ترويسة X-402-Payment، ثم أعد إرسال نفس المسار.

بناء ترويسة X-402-Payment لـ Base

ينشئ السكربت التالي دفعة x402 موقّعة على Base ويرسل طلب الشحن. يتطلّب حزمتي npm x402 وviem.

export EVM_PRIVATE_KEY=0xYOUR_PRIVATE_KEY

export X402_PAYMENT="$(
node --input-type=module <<'EOF'
import { createPaymentHeader } from "x402/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);
const amountUsd = 5;
const amountBaseUnits = String(Math.round(amountUsd * 1e6));

const header = await createPaymentHeader(signer, 2, {
  scheme: "exact",
  network: "base",
  maxAmountRequired: amountBaseUnits,
  resource: "https://api.venice.ai/api/v1/x402/top-up",
  description: "Venice x402 top-up",
  mimeType: "application/json",
  payTo: "0x2670B922ef37C7Df47158725C0CC407b5382293F",
  maxTimeoutSeconds: 300,
  asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  extra: { name: "USD Coin", version: "2" },
});

process.stdout.write(header);
EOF
)"

curl -X POST "https://api.venice.ai/api/v1/x402/top-up" \
  -H "X-402-Payment: $X402_PAYMENT"

استخدم أحدث استجابة PAYMENT-REQUIRED / accepts كمصدر للحقيقة في الإنتاج بدلًا من تثبيت هذه القيم برمجيًا. لشحنات Solana، ابنِ الدفعة من عنصر Solana المُرجَع في accepts. تستخدم عناصر Solana network: "solana"، وعملة USDC mint كـ asset، وقد تتضمّن بيانات وصفية خاصة بالشبكة مثل extra.feePayer.

الخطوة 4: إجراء طلب

بمجرد أن تمتلك المحفظة رصيدًا قابلًا للإنفاق، استدعِ أي نقطة نهاية مدعومة باستخدام ترويسة X-Sign-In-With-X:

export X402_AUTH=YOUR_BASE64_SIWX_HEADER

curl --request POST \
  --url https://api.venice.ai/api/v1/chat/completions \
  --header "Content-Type: application/json" \
  --header "X-Sign-In-With-X: $X402_AUTH" \
  --data '{
    "model": "kimi-k2-5",
    "messages": [
      {
        "role": "user",
        "content": "Hello from an x402-authenticated wallet."
      }
    ]
  }'

قد تتضمّن الاستجابات الناجحة ترويسة X-Balance-Remaining.

الخطوة 5: فحص المعاملات (اختياري)

راجع سجلّ معاملات المحفظة:

export WALLET_ADDRESS=0xYOUR_WALLET_ADDRESS_OR_SOLANA_ADDRESS
export X402_AUTH=YOUR_BASE64_SIWX_HEADER

curl --request GET \
  --url "https://api.venice.ai/api/v1/x402/transactions/$WALLET_ADDRESS?limit=10&offset=0" \
  --header "X-Sign-In-With-X: $X402_AUTH"

يتضمّن دفتر الأستاذ إدخالات مثل TOP_UP وCHARGE وREFUND. يقبل معامل المسار walletAddress إما عنوان EVM (0x...) أو عنوان Solana بصيغة base58.

المسارات المدعومة

مسارات الاستدلال المدفوعة

تدعم مسارات Venice المدفوعة العامة التالية مصادقة محفظة x402 حاليًا.

الفئة	نقاط النهاية
Chat	`POST /api/v1/chat/completions`, `POST /api/v1/responses`
Image	`POST /api/v1/image/generate`, `POST /api/v1/images/generations`, `POST /api/v1/image/upscale`, `POST /api/v1/image/edit`, `POST /api/v1/image/multi-edit`, `POST /api/v1/image/background-remove`
Embeddings	`POST /api/v1/embeddings`
Audio	`POST /api/v1/audio/speech`, `POST /api/v1/audio/transcriptions`, `POST /api/v1/audio/complete`, `POST /api/v1/audio/queue`, `POST /api/v1/audio/retrieve`
Video	`POST /api/v1/video/complete`, `POST /api/v1/video/queue`, `POST /api/v1/video/retrieve`, `POST /api/v1/video/transcriptions`

مسار شحن الرصيد

نقطة النهاية	المصادقة	الغرض
`POST /api/v1/x402/top-up`	الطلب الأولي: لا شيء. إعادة المحاولة: `X-402-Payment`	إضافة رصيد USDC إلى الرصيد القابل للإنفاق للمحفظة باستخدام خيار دفع مقبول على Base أو Solana

مسارات المحفظة فقط

تستخدم هذه المسارات X-Sign-In-With-X للهوية لكنها لا تخصم من الرصيد.

نقطة النهاية	الغرض
`GET /api/v1/x402/balance/{walletAddress}`	التحقق من الرصيد القابل للإنفاق لعنوان محفظة EVM أو Solana
`GET /api/v1/x402/transactions/{walletAddress}`	عرض سجلّ المعاملات لعنوان محفظة EVM أو Solana

الأخطاء

الحالة	السبب المحتمل	ما يجب فعله
`401`	حمولة Sign-In-With-X مشوّهة أو منتهية الصلاحية	أعد بناء `X-Sign-In-With-X` بـ nonce وطابع زمني جديدين
`402` على مسار مدفوع	الرصيد القابل للإنفاق غير كافٍ	اشحن وأعد المحاولة
`402` على `/x402/top-up`	متوقّع. هذا هو تدفّق بدء الدفع.	استخدم تفاصيل الدفع المُرجَعة لبناء `X-402-Payment` وأعد المحاولة
`403` على الرصيد أو المعاملات	عدم تطابق المحفظة	تأكّد من أن المحفظة المُصادق عليها تطابق معامل المسار `walletAddress`
`400` على شحن الرصيد	ترويسة دفع مشوّهة	أعد البناء من أحدث استجابة `402`

للوكلاء

التدفّق هو نفسه. خزّن المفاتيح الخاصة في متغيرات البيئة أو في مدير أسرار، وتحقّق من الرصيد قبل الطلبات لتجنّب رحلات 402 غير الضرورية.

مصادر ذات صلة

SDK عميل x402

عميل Venice x402 الرسمي لـ Node.js/TypeScript.

تسعير API

تحقّق من تسعير النماذج وكيفية احتساب Venice للاستخدام.

Chat Completions

مسار مدفوع شائع للوصول القائم على المحفظة.

مواصفات API

وثائق مرجعية ووصول إلى المواصفات الخام.

مصادقة المحفظة

ادفع بـ USDC

DIEM أولًا

​ما هو X402؟

​المتطلبات المسبقة

​البدء السريع

​مع الأدوات المتوافقة مع OpenAI

​الأدوات المساعدة المتاحة

​التدفّق اليدوي

​الخطوة 1: إنشاء ترويسة X-Sign-In-With-X

​الخطوة 2: التحقق من الرصيد

​الخطوة 3: شحن الرصيد

​بناء ترويسة X-402-Payment لـ Base

​الخطوة 4: إجراء طلب

​الخطوة 5: فحص المعاملات (اختياري)

​المسارات المدعومة

​مسارات الاستدلال المدفوعة

​مسار شحن الرصيد

​مسارات المحفظة فقط

​الأخطاء

​للوكلاء

​مصادر ذات صلة

SDK عميل x402

تسعير API

Chat Completions

مواصفات API

ما هو X402؟

المتطلبات المسبقة

البدء السريع

مع الأدوات المتوافقة مع OpenAI

الأدوات المساعدة المتاحة

التدفّق اليدوي

الخطوة 1: إنشاء ترويسة X-Sign-In-With-X

الخطوة 2: التحقق من الرصيد

الخطوة 3: شحن الرصيد

بناء ترويسة X-402-Payment لـ Base

الخطوة 4: إجراء طلب

الخطوة 5: فحص المعاملات (اختياري)

المسارات المدعومة

مسارات الاستدلال المدفوعة

مسار شحن الرصيد

مسارات المحفظة فقط

الأخطاء

للوكلاء

مصادر ذات صلة