Crypto RPC for Agents | Venice API Docs

يمنح Venice وكيلك كلاً من الاستدلال (230+ نموذجاً) والوصول إلى البلوكتشين (10 سلاسل EVM بالإضافة إلى Starknet) عبر اعتماد واحد. يستطيع وكيلك التفكير والتوقيع وإرسال المعاملات دون الحاجة إلى التعامل مع حسابات منفصلة لمزودي الاستدلال وRPC.

اعتماد واحد، قدرتان خارقتان

مفتاح API واحد (أو محفظة) لاستدلال LLM واستدعاءات JSON-RPC معاً.

دعم 11 سلسلة

Ethereum، Base، Arbitrum، Optimism، Polygon، Linea، Avalanche، BSC، Blast، zkSync Era، وStarknet (الشبكات الرئيسية وشبكات الاختبار).

رهن VVV للتمويل بدون تدخل بشري

قم برهن VVV على Base لكسب DIEM يومياً، وهو المسار التمويلي الوحيد المستقل تماماً لمفتاح API صادر. تتوفر أيضاً عمليات الشحن بالدولار الأمريكي والعملات الرقمية عبر لوحة التحكم.

مصادقة بدون مفتاح عبر x402

يستطيع الوكلاء المصادقة بتوقيع محفظة والدفع بـ USDC على Base أو Solana.

لماذا Venice للوكلاء على السلسلة؟

القدرة	ما يحصل عليه وكيلك
الاستدلال	230+ نموذجاً للنص والصورة والفيديو والصوت والتضمينات عبر نقطة نهاية واحدة متوافقة مع OpenAI
Crypto RPC	وكيل JSON-RPC 2.0 إلى 10 سلاسل EVM بالإضافة إلى Starknet (الشبكات الرئيسية وشبكات الاختبار)
المصادقة	مفتاح API قياسي أو مصادقة محفظة x402 (لا يلزم حساب Venice)
التمويل	مستقل: رهن VVV للحصول على DIEM يومي. عبر المتصفح: شحن بالدولار أو بالعملات الرقمية عبر لوحة التحكم
التجميع	حتى 100 استدعاء JSON-RPC لكل طلب، متعدد السلاسل بالتوازي
الحماية من التكرار	إعادات محاولة آمنة باستخدام رأس `Idempotency-Key`

المصادقة

اختر طريقة المصادقة التي تتناسب مع كيفية تشغيل وكيلك.

الطريقة	الأنسب لـ	كيف تعمل
مفتاح API	الوكلاء من جانب الخادم، عمليات النشر الثابتة	رأس `Authorization: Bearer <key>`. احصل على مفتاح من venice.ai/settings/api.
محفظة x402	الوكلاء المستقلون أو القائمون على العملات الرقمية أو قصيرو العمر	توقع المحفظة رسالة Sign-In-With-X وتدفع لكل طلب بـ USDC على Base أو Solana. لا يلزم حساب Venice. راجع دليل x402.

تتشارك كلتا الطريقتين نفس حدود المعدل والفوترة بائتمانات Venice.

يمكن للوكلاء المستقلين بحق إصدار مفتاح API الخاص بهم عن طريق رهن VVV على Base. راجع إنشاء مفتاح API للوكيل المستقل.

بداية سريعة مع Crypto RPC

أرسل أي طريقة JSON-RPC 2.0 إلى POST /crypto/rpc/{network}.

curl https://api.venice.ai/api/v1/crypto/rpc/ethereum-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_chainId",
    "params": [],
    "id": 1
  }'

الاستجابة:

{ "jsonrpc": "2.0", "id": 1, "result": "0x1" }

تتضمن رؤوس الاستجابة X-Venice-RPC-Credits (الائتمانات المخصومة) وX-Venice-RPC-Cost-USD (التكلفة بالدولار) وX-Request-ID (معرّف الربط).

الشبكات المدعومة

العائلة	الشبكة الرئيسية	شبكات الاختبار
Ethereum	`ethereum-mainnet`	`ethereum-sepolia`, `ethereum-holesky`
Base	`base-mainnet`	`base-sepolia`
Arbitrum	`arbitrum-mainnet`	`arbitrum-sepolia`
Optimism	`optimism-mainnet`	`optimism-sepolia`
Polygon	`polygon-mainnet`	`polygon-amoy`
Linea	`linea-mainnet`	`linea-sepolia`
Avalanche C-Chain	`avalanche-mainnet`	`avalanche-fuji`
BNB Smart Chain	`bsc-mainnet`	`bsc-testnet`
Blast	`blast-mainnet`	`blast-sepolia`
zkSync Era	`zksync-mainnet`	`zksync-sepolia`
Starknet	`starknet-mainnet`	`starknet-sepolia`

استخدم GET /crypto/rpc/networks للحصول على القائمة الحية الموثوقة.

مستويات الطرق

يتم تصنيف الطرق إلى ثلاثة مستويات ائتمانية. التكلفة الإجمالية = baseCredits[chain] × methodTier.

المستوى	المضاعف	أمثلة
قياسي	1x	`eth_call`, `eth_getBalance`, `eth_blockNumber`, `eth_sendRawTransaction`, `eth_getLogs`, `eth_getTransactionReceipt`, `eth_estimateGas`
متقدم	2x	`trace_block`, `trace_call`, `trace_transaction`, `debug_traceCall`, `debug_traceTransaction`
كبير	4x	`trace_replayBlockTransactions`, `trace_replayTransaction`, `txpool_content`

القائمة الكاملة وتفاصيل الأسعار في مرجع Crypto RPC API.

وصفات الوكيل

أنماط شائعة للوكلاء الذكيين الذين يحتاجون إلى القراءة والكتابة على السلسلة.

قراءة رصيد العملة الأصلية لمحفظة

curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0xYourWalletAddress", "latest"],
    "id": 1
  }'

قراءة رصيد رمز ERC-20

استدعِ محدد balanceOf(address) باستخدام eth_call. حقل data هو المحدد ذو الأربعة بايتات (0x70a08231) متبوعاً بعنوان المحفظة المُكمَّل من اليسار إلى 32 بايت. الأسهل ترك مكتبة تتولى الترميز:

import { encodeFunctionData, parseAbi } from 'viem'

const data = encodeFunctionData({
  abi: parseAbi(['function balanceOf(address) view returns (uint256)']),
  args: ['0xWalletAddress'],
})

const response = await fetch('https://api.venice.ai/api/v1/crypto/rpc/base-mainnet', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'eth_call',
    params: [{ to: '0xacfE6019Ed1A7Dc6f7B508C02d1b04ec88cC21bf', data }, 'latest'],
    id: 1,
  }),
})

عنوان العقد أعلاه هو VVV على Base. استبدله بأي عقد ERC-20.

إرسال معاملة موقّعة (دورة الحياة الكاملة)

لا يحتفظ Venice أبداً بمفاتيحك الخاصة. يجمع الوكيل معاملات tx عبر قراءات RPC، ويوقعها محلياً بمكتبة مثل viem أو ethers، ثم يمرر السداسي العشري الخام عبر Venice.

احصل على الـ nonce التالي

curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0xAgentWallet","pending"],"id":1}'

استخدم "pending" حتى لا تتعارض عمليات الإرسال المتتالية.

احصل على سعر الغاز

curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}'

لسلاسل EIP-1559، يُفضل استخدام eth_feeHistory لحساب maxFeePerGas وmaxPriorityFeePerGas.

قدّر الغاز

curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"from":"0xAgentWallet","to":"0xRecipient","value":"0x0","data":"0x..."}],"id":1}'

وقّع محلياً

import { privateKeyToAccount } from 'viem/accounts'
import { base } from 'viem/chains'

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY)

const signed = await account.signTransaction({
  chainId: base.id,
  nonce,                  // من الخطوة 1
  gas,                    // من الخطوة 3
  maxFeePerGas,           // من الخطوة 2 (سجل الرسوم)
  maxPriorityFeePerGas,   // من الخطوة 2 (سجل الرسوم)
  to: '0xRecipient',
  value: 0n,
  data: '0x...',
})

أرسل عبر Venice

curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Idempotency-Key: agent-tx-<id>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0xSignedHex"],"id":1}'

عيّن دائماً Idempotency-Key عند إعادة التمرير حتى لا تتسبب أي مشكلة شبكية في بث المعاملة مرتين.

استعلم عن الإيصال

curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0xTxHash"],"id":1}'

استعلم كل بضع ثوانٍ حتى تكون قيمة result غير فارغة. تحقق من result.status ("0x1" = نجاح).

يتم تسجيل كل استدعاء eth_sendRawTransaction من جانب الخادم مع تجزئة المعاملة والشبكة ومعرف الطلب ومعرف المستخدم المتصل. لا يتم الاحتفاظ بالحمولة الموقّعة نفسها. يوجد هذا السجل التدقيقي حتى يمكن تتبع المفاتيح المخترقة المستخدمة في عمليات تمرير غير مشروعة وإعادتها إلى الحساب المسؤول.

تجميع استدعاءات متعددة (فحص محفظة متعددة السلاسل)

أرسل حتى 100 كائن JSON-RPC في طلب واحد. يتم التحقق من صحة كل منها وفوترته بشكل مستقل.

curl https://api.venice.ai/api/v1/crypto/rpc/ethereum-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1 },
    { "jsonrpc": "2.0", "method": "eth_getBalance", "params": ["0xWallet", "latest"], "id": 2 },
    { "jsonrpc": "2.0", "method": "eth_gasPrice", "params": [], "id": 3 }
  ]'

للقراءات متعددة السلاسل (استدعاء واحد لكل سلسلة)، أصدر طلبات متوازية إلى نقاط نهاية {network} مختلفة.

إعادات المحاولة الآمنة باستخدام الحماية من التكرار

عيّن رأس Idempotency-Key إلى أي سلسلة تطابق [A-Za-z0-9_-]{1,255}. يخزن Venice الاستجابة مؤقتاً لمدة 24 ساعة بناءً على المفتاح (user, key). ترجع إعادات التشغيل النتيجة المخزنة مع Idempotent-Replayed: true ولا تتقاضى أي رسوم.

curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Idempotency-Key: agent-tx-2026-04-21-001" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_sendRawTransaction",
    "params": ["0xSignedRawTxHex"],
    "id": 1
  }'

هذا أمر بالغ الأهمية لعمليات تمرير المعاملات حيث قد تتسبب أي مشكلة شبكية في بث وكيلك للمعاملة نفسها مرتين.

تمويل مفتاح API الخاص بالوكيل

بمجرد حصول الوكيل على مفتاح Venice API، يحتاج إلى رصيد قابل للإنفاق على الحساب الأساسي قبل أن تقبل نقاط النهاية المدفوعة المفتاح. هناك طريقتان لإضافة الرصيد:

المسار	مستقل؟	كيف يعمل
DIEM من رهن VVV	نعم	قم برهن VVV في عقد Venice الذكي للرهن على Base. تخصيص DIEM اليومي للمحفظة يتناسب مع حصتها من مجمع الرهن. يجب أن يكون لدى الحساب 0.1 DIEM على الأقل متراكماً قبل أن يصبح أي DIEM قابلاً للإنفاق. يتم تحديث DIEM في الساعة 00:00 UTC. لزيادة الإنفاق اليومي، قم برهن مزيد من VVV.
شحن بالدولار أو بالعملات الرقمية عبر لوحة التحكم	لا (متصفح)	سجل الدخول إلى venice.ai بنفس المحفظة (Sign-In-With-Ethereum)، ثم أضف الائتمانات في الإعدادات > API. كل من Stripe (بطاقة) وCoinbase (عملات رقمية) يعملان خلف هذه الصفحة ويتطلبان متصفحاً. لا تنتهي صلاحية الائتمانات أبداً.

بالنسبة لوكيل يعمل دون إشراف، DIEM عبر رهن VVV هو حالياً المسار التمويلي الوحيد المستقل تماماً لمفتاح API صادر. إذا تجاوز الإنفاق اليومي للوكيل تخصيص DIEM، فالخيارات الواقعية هي: رهن مزيد من VVV، أو أن يقوم مشغل بتسجيل الدخول والشحن بالدولار أو العملات الرقمية.

الرهن المستقل لـ VVV وتوليد المفاتيح

يستطيع الوكيل المستقل بحق إدارة محفظة VVV الخاصة به على Base ورهنها وإصدار مفتاح Venice API الخاص به دون أي تدخل بشري. التدفق الكامل:

احصل على VVV وETH للغاز

أرسل VVV إلى محفظة الوكيل (أو اجعل الوكيل يقوم بالتبديل على Aerodrome أو Uniswap)، بالإضافة إلى مبلغ صغير من ETH على Base لمعاملتي الرهن.

رهن VVV

قم بـ approve لعقد الرهن على رمز VVV، ثم stake(amount) على 0x321b7ff75154472B18EDb199033fF4D116F340Ff. يتم تحديث رصيد sVVV للمحفظة بشكل ذرّي مع الرهن.

إصدار مفتاح API

يُرجع GET /api/v1/api_keys/generate_web3_key رمز JWT تنتهي صلاحيته بعد 15 دقيقة من الإصدار. وقّع الرمز الخام بمحفظة الرهن، ثم POST العنوان والتوقيع والرمز مرة أخرى. يُرجع Venice مفتاح API مرتبطاً بحساب المستخدم المشتق من تلك المحفظة.

يتطلب الإصدار فقط رصيد sVVV غير صفري، لذا فإن 1 VVV مرهون كافٍ لتلقي مفتاح. الإنفاق بالمفتاح مسألة منفصلة، تحكمها جدول التمويل أعلاه. راجع إنشاء مفتاح API للوكيل المستقل للاطلاع على الشرح الكامل مع الكود والمرجع الكامل للأخطاء.

مصادقة محفظة x402 في 30 ثانية

إذا كان وكيلك يمتلك بالفعل محفظة Base أو Solana، فيمكنك تخطي مفتاح API تماماً. تتولى SDK venice-x402-client توقيع Sign-In-With-X وعمليات الشحن وتتبع الرصيد.

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-6',
  messages: [{ role: 'user', content: 'What is the latest block on Base?' }]
})

تعمل مصادقة المحفظة نفسها مقابل /crypto/rpc/{network} للقراءة والكتابة على البلوكتشين. تفاصيل البروتوكول الكاملة في دليل x402.

التسعير

يتم فوترة Crypto RPC بائتمانات Venice. تحتوي كل استجابة على X-Venice-RPC-Credits (الائتمانات المخصومة) وX-Venice-RPC-Cost-USD (التكلفة بالدولار) حتى يتمكن وكيلك من تتبع الإنفاق لكل طلب.

الائتمانات الأساسية لكل سلسلة

الائتمانات الأساسية	السلاسل
20	Ethereum، Base، Optimism، Arbitrum، Polygon، Linea، Avalanche، BSC، Blast، Starknet
30	zkSync Era

أمثلة على التكلفة

الأسعار المرصودة لمستويات الطرق القياسية والمتقدمة والكبيرة:

الاستدعاء	الائتمانات	التكلفة بالدولار
`eth_call` على Ethereum (20 × 1x)	20	~$0.0000140
`trace_transaction` على Ethereum (20 × 2x)	40	~$0.0000280
`trace_replayTransaction` على Ethereum (20 × 4x)	80	~$0.0000560
`eth_call` على zkSync (30 × 1x)	30	~$0.0000210

ثق دائماً برأس استجابة X-Venice-RPC-Cost-USD للحصول على التكلفة الموثوقة. تُفوتر العناصر الخاطئة في طلبات التجميع بسعر ثابت قدره 5 ائتمانات لكل منها.

حدود المعدل

المستوى	الطلبات في الدقيقة
قياسي	100
الموظفون	1,000

عند التجاوز، تُرجع نقطة النهاية 429 مع رؤوس استجابة X-RateLimit-* القياسية.

معالجة الأخطاء

استجابات HTTP الشائعة التي يجب على وكيلك التعامل معها:

الحالة	المعنى	ما يجب فعله
`400`	طريقة JSON-RPC غير مدعومة أو غير معينة، أو دفعة مشوهة	تحقق من الطريقة مقابل قائمة الطرق المسموح بها. يذكر متن الخطأ اسم الطريقة المخالفة.
`400`	إعادة تشغيل `Idempotency-Key` بمتن مختلف	استخدم مفتاحاً جديداً للطلبات المتميزة.
`402`	لا يوجد رأس مصادقة على الإطلاق (يتضمن متن الاستجابة `authOptions` يسرد كلا مساري المصادقة المدعومين)، أو نفاد الائتمانات مع رأس مصادقة صالح	إذا لم تكن هناك مصادقة: أرفق `Authorization: Bearer ...` أو رأس x402 `X-Sign-In-With-X`. إذا نفدت الائتمانات: بمفتاح Bearer، قم بتمويل الحساب (DIEM، دولار، أو شحن لوحة التحكم)؛ مع مصادقة x402، استدعِ `POST /api/v1/x402/top-up` مباشرة.
`429`	تم بلوغ حد المعدل (100 طلب/دقيقة قياسي، 1,000 طلب/دقيقة للموظفين)	احترم `X-RateLimit-Reset` وتراجع. اجمع حتى 100 استدعاء لكل طلب لاستهلاك الحد.
`5xx`	عقبة في عقدة RPC الخلفية	أعد المحاولة بنفس `Idempotency-Key` لتجنب الفوترة المزدوجة.

تأتي أخطاء عناصر الدفعة (مثل معاملات غير صالحة في أحد N استدعاء) داخل استجابة 200 OK مع حقل error بصيغة JSON-RPC على العنصر المخالف. تُفوتر تلك العناصر بسعر ثابت قدره 5 ائتمانات لكل منها.

غير مدعوم

يتم رفض هذه الفئات من الطرق عمداً:

WebSocket فقط (eth_subscribe, eth_unsubscribe): الوكيل HTTP فقط. استخدم الاستعلام بدلاً من ذلك.
المرشحات ذات الحالة (eth_newFilter, eth_getFilterChanges, إلخ): حالة المرشح مثبتة بخلفية واحدة وتُكسر عبر وكيل موزع الحمل. استخدم eth_getLogs بدلاً من ذلك.
الطرق التي تحمل المفاتيح (eth_sign, eth_accounts, eth_mining): لا يحتفظ المزودون المستضافون بمفاتيح المستخدمين. وقّع من جانب العميل وأرسل عبر eth_sendRawTransaction.
الطرق غير المعينة: أي شيء غير مدرج في القائمة المسموح بها يُرجع 400. اتصل بالدعم لطلب إضافات.

الموارد

مرجع Crypto RPC API

قائمة الطرق الكاملة، التسعير، ورؤوس الاستجابة

الشبكات المدعومة

قائمة حية بأسماء الشبكات المدعومة

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

المصادقة والدفع بمحفظة Base أو Solana

مفتاح API للوكيل المستقل

أصدر مفتاحك الخاص عبر رهن VVV

مجموعة Postman

27 مثالاً جاهزاً للتشغيل لـ Crypto RPC

التسعير

DIEM، تسعير الائتمانات، وخيارات الدفع

اعتماد واحد، قدرتان خارقتان

دعم 11 سلسلة

رهن VVV للتمويل بدون تدخل بشري

مصادقة بدون مفتاح عبر x402

​لماذا Venice للوكلاء على السلسلة؟

​المصادقة

​بداية سريعة مع Crypto RPC

​الشبكات المدعومة

​مستويات الطرق

​وصفات الوكيل

​قراءة رصيد العملة الأصلية لمحفظة

​قراءة رصيد رمز ERC-20

​إرسال معاملة موقّعة (دورة الحياة الكاملة)

​تجميع استدعاءات متعددة (فحص محفظة متعددة السلاسل)

​إعادات المحاولة الآمنة باستخدام الحماية من التكرار

​تمويل مفتاح API الخاص بالوكيل

​الرهن المستقل لـ VVV وتوليد المفاتيح

​مصادقة محفظة x402 في 30 ثانية

​التسعير

​الائتمانات الأساسية لكل سلسلة

​أمثلة على التكلفة

​حدود المعدل

​معالجة الأخطاء

​غير مدعوم

​الموارد

مرجع Crypto RPC API

الشبكات المدعومة

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

مفتاح API للوكيل المستقل

مجموعة Postman

التسعير

لماذا Venice للوكلاء على السلسلة؟

المصادقة

بداية سريعة مع Crypto RPC

الشبكات المدعومة

مستويات الطرق

وصفات الوكيل

قراءة رصيد العملة الأصلية لمحفظة

قراءة رصيد رمز ERC-20

إرسال معاملة موقّعة (دورة الحياة الكاملة)

تجميع استدعاءات متعددة (فحص محفظة متعددة السلاسل)

إعادات المحاولة الآمنة باستخدام الحماية من التكرار

تمويل مفتاح API الخاص بالوكيل

الرهن المستقل لـ VVV وتوليد المفاتيح

مصادقة محفظة x402 في 30 ثانية

التسعير

الائتمانات الأساسية لكل سلسلة

أمثلة على التكلفة

حدود المعدل

معالجة الأخطاء

غير مدعوم

الموارد