X402

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

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

صادِق باستخدام حمولة Sign-In-With-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!' }]
})

يولّد العميل ترويسة 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()`
Embeddings	`embeddings()`
Models	`models()`
Wallet	`getBalance()`, `getTransactions()`, `topUp()`

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

إذا كنت لا تستخدم الـ SDK أو تحتاج إلى فهم البروتوكول الأساسي، فإليك التدفّق خطوة بخطوة. لمحفظة جديدة، افترض أنك تحتاج إلى شحن الرصيد أولًا ما لم تكن تمتلك بالفعل رصيد DIEM قابلًا للإنفاق. تتوقع Venice برهان sign-in-with-x الخاص بـ x402 في ترويسة SIGN-IN-WITH-X: وهو JSON مُرمَّز بـ Base64 يحتوي على حقول الرسالة الموقّعة (domain وaddress وuri وversion وchainId وtype وnonce وissuedAt، إضافةً إلى الحقول الاختيارية expirationTime وnotBefore وstatement وresources) مع signature. تعيد Venice بناء الرسالة الموقّعة من هذه الحقول. توقّع محافظ EVM رسالة SIWE وفق EIP-4361 على Base وتضبط type على eip191، بما في ذلك محافظ العقود الذكية. توقّع محافظ Solana رسالة تسجيل الدخول الخاصة بـ Solana باستخدام Ed25519. في JSON، تكون قيمة chainId هي معرّف CAIP-2 (eip155:8453)، بينما يحمل سطر Chain ID في الرسالة الموقّعة المرجع المجرّد (8453). لا يزال اسم الترويسة القديم X-Sign-In-With-X مقبولًا، وكذلك الحمولات الأقدم التي ترسل message الموقّعة نفسها. لا يمكن استخدام كل رسالة موقّعة إلا مرة واحدة. وقّع رسالة جديدة بـ nonce جديد لكل طلب، سواء كان من إنشائك أو قيمة nonce من أحدث تحدٍّ 402، وأرسلها خلال 5 دقائق من وقت issuedAt الخاص بها. تؤدي إعادة استخدام رسالة إلى إرجاع 401 (nonce already used)، وكذلك الرسالة الصادرة قبل أكثر من 5 دقائق. بالنسبة لـ 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)

async function createSiwxHeader(resourceUrl: string): Promise<string> {
  const now = new Date()
  const fields = {
    domain: 'api.venice.ai',
    address: wallet.address,
    statement: 'Sign in to Venice AI',
    uri: resourceUrl,
    version: '1',
    nonce: generateNonce(),
    issuedAt: now.toISOString(),
    expirationTime: new Date(now.getTime() + 5 * 60 * 1000).toISOString(),
  }

  const message = new SiweMessage({ ...fields, chainId: 8453 }).prepareMessage()
  const signature = await wallet.signMessage(message)

  return Buffer.from(JSON.stringify({ ...fields, chainId: 'eip155:8453', type: 'eip191', signature }), 'utf8').toString('base64')
}

const response = await fetch('https://api.venice.ai/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'SIGN-IN-WITH-X': await createSiwxHeader('https://api.venice.ai/api/v1/chat/completions'),
  },
  body: JSON.stringify({
    model: 'kimi-k2-5',
    messages: [{ role: 'user', content: 'Hello!' }],
  }),
})

استدعِ createSiwxHeader() مباشرةً قبل كل طلب. في أمثلة curl أدناه، يجب أن تكون X402_AUTH ترويسة موقّعة حديثًا لكل استدعاء.

الخطوة 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 "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 الذي تريد الدفع به، واستخدم تلك التفاصيل الدقيقة لبناء ترويسة PAYMENT-SIGNATURE، ثم أعد إرسال نفس المسار. لا يزال اسما الترويستين القديمين X-402-Payment وX-PAYMENT مقبولين.

إرسال USDC مباشرةً إلى عنوان payTo لا يشحن رصيدك. لا يُضاف الرصيد إلا عندما تتم تسوية PAYMENT-SIGNATURE موقّعة عبر POST /x402/top-up. الشبكتان المدعومتان هما Base وSolana فقط، لذا لا تُحتسب أي USDC تُرسل على أي سلسلة أخرى، بما في ذلك الشبكة الرئيسية لـ Ethereum. تقرأ مسارات الرصيد والمعاملات سجلّ Venice وليس السلسلة، لذا لا تُظهر شيئًا بعد تحويل عادي.

بناء ترويسة PAYMENT-SIGNATURE لـ 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 "PAYMENT-SIGNATURE: $X402_PAYMENT"

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

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

بمجرد أن تمتلك المحفظة رصيدًا قابلًا للإنفاق، استدعِ أي نقطة نهاية مدعومة باستخدام ترويسة 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 "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 "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/voices`, `POST /api/v1/audio/complete`, `POST /api/v1/audio/queue`, `POST /api/v1/audio/retrieve`, `POST /api/v1/audio/voice-changer/queue`, `POST /api/v1/audio/voice-changer/retrieve`, `POST /api/v1/audio/voice-changer/complete`
Video	`POST /api/v1/video/complete`, `POST /api/v1/video/queue`, `POST /api/v1/video/retrieve`
Decisions	`POST /api/v1/decisions`, `POST /api/v1/systemone`
Tools	`POST /api/v1/augment/search`, `POST /api/v1/augment/scrape`, `POST /api/v1/augment/text-parser`
Blockchain RPC	`POST /api/v1/crypto/rpc/{network}`

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

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

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

تستخدم هذه المسارات 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 مشوّهة أو منتهية الصلاحية أو مستخدمة مسبقًا	وقّع رسالة `SIGN-IN-WITH-X` جديدة بـ nonce جديد لهذا الطلب
`402` مع `"error": "Authentication required"`	لم تُرسَل ترويسة `SIGN-IN-WITH-X` ولا مفتاح API	أضف ترويسة Sign-In-With-X. يحتوي الحقل `extensions` في الاستجابة على nonce جديد للتوقيع.
`402` على مسار مدفوع	الرصيد القابل للإنفاق غير كافٍ	اشحن وأعد المحاولة
`402` على `/x402/top-up`	متوقّع. هذا هو تدفّق بدء الدفع.	استخدم تفاصيل الدفع المُرجَعة لبناء `PAYMENT-SIGNATURE` وأعد المحاولة
`403` على الرصيد أو المعاملات	عدم تطابق المحفظة	تأكّد من أن المحفظة المُصادق عليها تطابق معامل المسار `walletAddress`
`400` على شحن الرصيد	ترويسة دفع مشوّهة	أعد البناء من أحدث استجابة `402`

للوكلاء

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

SDK عميل x402

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

تسعير API

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

Chat Completions

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

مواصفات API

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

التوثيق

البدء

النص والدردشة

الصورة

الفيديو

الصوت

البحث وRAG

الوكلاء والتكاملات

أدوات البرمجة

أدوات الوكلاء

حِزم SDK والأُطر

X402

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

ادفع بـ USDC

DIEM أولًا

ما هو X402؟

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

البدء السريع

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

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

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

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

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

بناء ترويسة PAYMENT-SIGNATURE لـ Base

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

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

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

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

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

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

الأخطاء

للوكلاء

SDK عميل x402

تسعير API

Chat Completions

مواصفات API

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

ادفع بـ USDC

DIEM أولًا

​ما هو X402؟

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

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

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

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

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

​الخطوة 1: إنشاء ترويسة SIGN-IN-WITH-X

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

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

​بناء ترويسة PAYMENT-SIGNATURE لـ Base

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

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

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

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

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

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

​الأخطاء

​للوكلاء

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

SDK عميل x402

تسعير API

Chat Completions

مواصفات API

ما هو X402؟

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

البدء السريع

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

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

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

الخطوة 1: إنشاء ترويسة SIGN-IN-WITH-X

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

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

بناء ترويسة PAYMENT-SIGNATURE لـ Base

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

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

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

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

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

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

الأخطاء

للوكلاء

مصادر ذات صلة