إنشاء مفتاح API للوكلاء المستقلين

​

المتطلبات

• محفظة EVM على Base يتحكم بها الوكيل (مفتاح خاص في متغير بيئة أو مدير أسرار).
• كمية صغيرة من ETH على Base للـ gas (الـ staking يتطلب معاملتين: approve ثم stake).
• أي كمية غير صفرية من VVV للـ stake. تتطلب endpoint الإصدار فقط أن يكون لدى المحفظة رصيد sVVV غير صفري، لذا VVV واحد يكفي لإصدار مفتاح. راجع الدفع للاستدلال لمعرفة ما تحتاجه لاستدعاء endpoints مدفوعة فعليًا.

​

الخطوات

1

احصل على VVV

أرسل VVV إلى محفظة الوكيل، أو اجعل الوكيل يقوم بمبادلة على DEX مثل Aerodrome أو Uniswap.عقد token VVV على Base: 0xacfE6019Ed1A7Dc6f7B508C02d1b04ec88cC21bf

2

قم بـ stake لـ VVV مع Venice

قم بـ stake لـ VVV في Venice Staking Smart Contract عند 0x321b7ff75154472B18EDb199033fF4D116F340Ff. هذه معاملتان:

1. approve(spender, amount) على token VVV، حيث spender هو عقد الـ staking.
2. stake(amount) على عقد الـ staking.

عندما تؤكَّد المعاملة الثانية، ينخفض رصيد VVV للمحفظة ويزداد رصيد sVVV الخاص بها بنفس المقدار. تقرأ endpoint الإصدار رصيد sVVV لتأكيد أن المحفظة قد قامت بـ stake.

3

اطلب رسالة تحدٍّ للمحفظة

استدعِ GET /api/v1/api_keys/generate_web3_key?address=<wallet address> للحصول على رسالة تحدٍّ EIP-4361 (Sign-In with Ethereum) قصيرة الأمد. الـ endpoint غير مُصادَقة، لكن رسالة التحدي مرتبطة بالعنوان الذي ترسله ولا يمكن استخدامها إلا بتلك المحفظة.

curl --request GET \
  --url 'https://api.venice.ai/api/v1/api_keys/generate_web3_key?address=<wallet address>'

تحتوي الاستجابة على message و nonce و expiresAt:

{
  "data": {
    "message": "api.venice.ai wants you to sign in with your Ethereum account:\n0x...\n\nAuthorize Venice API key creation. Only sign this on venice.ai — anyone holding this signature can create an API key on your Venice account.\n\nURI: https://api.venice.ai/api/v1/api_keys/generate_web3_key\nVersion: 1\nChain ID: 8453\nNonce: 9f2c1d6b4a8e05337c1b9d2e6f4a7c81\nIssued At: 2026-06-30T11:02:41.167Z\nExpiration Time: 2026-06-30T11:17:41.167Z\nResources:\n- urn:venice:api-key:create",
    "nonce": "9f2c1d6b4a8e05337c1b9d2e6f4a7c81",
    "expiresAt": "2026-06-30T11:17:41.167Z"
  },
  "success": true
}

تنتهي صلاحية رسالة التحدي بعد 15 دقيقة من إصدارها وهي للاستخدام مرة واحدة — تُستهلك عند إصدار أول مفتاح بها. اطلب رسالة جديدة لكل مفتاح.

4

وقّع رسالة التحدي بمحفظة الـ staking

وقّع سلسلة message كما هي بالمحفظة التي تحمل VVV المُكدَّس. هذا personal_sign قياسي. كلا ethers.Wallet.signMessage(message) و account.signMessage({ message }) من viem يُنتجان التوقيع الصحيح.لا تُعِد تنسيق الرسالة أو تغيير أسطرها أو توليدها من جديد. تتحقق Venice من التوقيع على البايتات نفسها التي أصدرتها، وتعيد فحص domain و URI و Chain ID ونص البيان والعنوان داخلها بشكل مستقل.

5

أصدر مفتاح API

POST العنوان والتوقيع ورسالة التحدي إلى نفس الـ endpoint، بالإضافة إلى نوع المفتاح الذي تريده.

curl --request POST \
  --url https://api.venice.ai/api/v1/api_keys/generate_web3_key \
  --header 'Content-Type: application/json' \
  --data '{
    "address": "<wallet address>",
    "signature": "<signature of the challenge message>",
    "message": "<the unmodified challenge message>",
    "apiKeyType": "INFERENCE",
    "description": "Agent key minted on <date>"
  }'

الحقول المطلوبة: address و signature و message و apiKeyType (INFERENCE أو ADMIN).الحقول الاختيارية: description و expiresAt و consumptionLimit (يحد من إجمالي الإنفاق على هذا المفتاح، بالعملة usd أو vcu أو diem).عند النجاح، تحتوي الاستجابة على سلسلة apiKey المُصدَرة. خزّنها في مخزن أسرار الوكيل واستخدمها كـ Bearer token عادي (Authorization: Bearer <key>).

​

مثال شامل

import { ethers } from "ethers"

const wallet = new ethers.Wallet(process.env.WALLET_PRIVATE_KEY!)
const address = wallet.address

const challengeResponse = await fetch(
  `https://api.venice.ai/api/v1/api_keys/generate_web3_key?address=${address}`,
)
const { data: { message } } = await challengeResponse.json()

const signature = await wallet.signMessage(message)

const mintResponse = await fetch("https://api.venice.ai/api/v1/api_keys/generate_web3_key", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    address,
    signature,
    message,
    apiKeyType: "INFERENCE",
    description: "Agent key",
  }),
})

const result = await mintResponse.json()
if (!mintResponse.ok) {
  throw new Error(`Mint failed: ${result.error}`)
}

console.log("Minted key:", result.data.apiKey)

​

مرجع الأخطاء

​

لماذا ترتبط رسالة التحدي بالمحفظة وتُستخدم مرة واحدة

• الارتباط بالعنوان. تذكر رسالة التحدي المحفظة التي صدرت لها. لا يمكن لمحفظة أخرى توقيع رسالة تحدٍّ حصل عليها طرف مختلف واستخدامها.
• nonce للاستخدام مرة واحدة. تتتبع Venice الـ nonce على الخادم وتستهلكه عند أول إصدار ناجح. التوقيع الواحد يُصدر مفتاحًا واحدًا بالضبط، لذا لا يمكن إعادة استخدام توقيع مُلتقَط للحصول على مفاتيح إضافية.
• بيان مقروء. تنص الرسالة صراحةً على أن التوقيع يُصرّح بإنشاء مفتاح Venice API، فتُظهر واجهة المحفظة مثل MetaMask للموقّع ما يوافق عليه بدلًا من كتلة بيانات ثنائية.

​

الدفع للاستدلال

1. قم بـ stake لمزيد من VVV بحيث تغطي حصة DIEM اليومية إنفاق الوكيل. يلتقط المفتاح المُصدَر هذا تلقائيًا.
2. استخدم تدفق محفظة x402 بدلًا من مفتاح API. مع x402 يوقّع الوكيل رسالة Sign-In-With-X لكل طلب، ويشحن مباشرة بـ USDC على Base أو Solana عبر POST /api/v1/x402/top-up، ويدفع لكل طلب. رصيد x402 USDC مرتبط بالمحفظة وليس بالمستخدم، لذا فهو لا يظهر كرصيد لمفتاح Bearer المُصدَر، لكنه يسمح لنفس المحفظة بدفع الاستدلال برمجيًا.

​

موارد ذات صلة