> ## Documentation Index > Fetch the complete documentation index at: https://docs.venice.ai/llms.txt > Use this file to discover all available pages before exploring further. # X402 > ادخل إلى Venice API دون مفتاح API بالدفع لكل طلب عبر بروتوكول x402 والمصادقة بمحفظة crypto على Base. يتيح لك X402 استخدام مسارات Venice API المدفوعة عن طريق المصادقة بمحفظة والاحتفاظ برصيد USDC مدفوع مسبقًا. لا حاجة إلى مفتاح API أو حساب. وقّع رسالة، واشحن الرصيد على Base أو Solana، واستدعِ أي مسار مدعوم. صادِق باستخدام حمولة Sign-In-With-X موقّعة في ترويسة `X-Sign-In-With-X`. احتفظ برصيد قابل للإنفاق باستخدام USDC على Base أو Solana. إذا كانت المحفظة مرتبطة بحساب Venice يمتلك رصيد DIEM، فيُنفَق ذلك أولًا. ## ما هو X402؟ [X402](https://www.x402.org/) هو معيار دفع مفتوح يسمح للتطبيقات والوكلاء بالدفع مقابل الخدمات برمجيًا باستخدام العملة المشفّرة. تدعم Venice X402 بحيث يمكن للمحافظ المصادقة والدفع مقابل الاستدلال مباشرة بـ USDC على Base أو Solana. ## المتطلبات المسبقة * محفظة على Base أو Solana * عملة أصلية للغاز على السلسلة المختارة، مثل ETH على Base أو SOL على Solana * USDC على السلسلة المختارة (أو رصيد مدعوم بـ DIEM قائم من حساب Venice مرتبط) فكّر في استخدام محفظة مخصّصة للأتمتة بدلًا من محفظة الخزينة الرئيسية. ## البدء السريع يوفّر SDK [`venice-x402-client`](https://github.com/veniceai/x402-client) أدوات مساعدة لمصادقة المحفظة وشحن الرصيد وتتبّع الرصيد. ```bash theme={"system"} npm install venice-x402-client ``` ```typescript theme={"system"} 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` لإضافة مصادقة المحفظة إلى أي طلب: ```typescript theme={"system"} 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 قابلًا للإنفاق. ### الخطوة 1: إنشاء ترويسة X-Sign-In-With-X تتوقّع 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. تبدأ الرسالة الموقّعة بـ ` wants you to sign in with your Solana account:`، يتبعها عنوان المحفظة والحقول القياسية `URI` و`Version` و`Chain ID` و`Nonce` و`Issued At` و`Expiration Time` الاختياري. ```typescript theme={"system"} 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: التحقق من الرصيد قبل إجراء طلب مدفوع، تحقّق من أن المحفظة تمتلك رصيدًا قابلًا للإنفاق: ```bash theme={"system"} 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: ```bash theme={"system"} 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`. ```bash theme={"system"} export EVM_PRIVATE_KEY=0xYOUR_PRIVATE_KEY ``` ```bash theme={"system"} 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`: ```bash theme={"system"} 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: فحص المعاملات (اختياري) راجع سجلّ معاملات المحفظة: ```bash theme={"system"} 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` غير الضرورية. *** ## مصادر ذات صلة عميل Venice x402 الرسمي لـ Node.js/TypeScript. تحقّق من تسعير النماذج وكيفية احتساب Venice للاستخدام. مسار مدفوع شائع للوصول القائم على المحفظة. وثائق مرجعية ووصول إلى المواصفات الخام.