تهيئة التجارة بلا واجهة لعصر النماذج اللغوية الوكيلة

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

الطرف الأمامي التالي لا ينظر. إنه يقرأ. المشتري يتحول إلى وكيل: برنامج له هدف وميزانية وحلقة أدوات، يُرسَل ليجد خطة أو معالج GPU أو واجهة API للمدفوعات. يشتري ممن يستطيع فهمه والدفع له دون أن يستعين بإنسان. إذا كان عملك يحتاج إلى شخص يقرأ الصفحة، أو يغلق شريط ملفات تعريف الارتباط، أو يفتح رسالة تأكيد، أو يكتب رقم بطاقة، انتقل الوكيل إلى النتيجة التالية.

هذه هي الأطروحة. لا بد أن يكون العمل مقروءًا وقابلًا لإتمام المعاملة من نموذج لغوي بلا إنسان في الحلقة. المقروء يعني أن الوكيل يستطيع أن يعرف ماذا تبيع، وبكم، وكيف يبدأ. القابل لإتمام المعاملة يعني أنه يستطيع أن يبدأ ويدفع ويستلم الشيء عبر واجهة API، وحده.

إليك ما يقتضيه ذلك، نقطة نقطة، مع ما تطرحه Hanzo اليوم. كل عنوان في ما يلي يجيب دون حساب، فتستطيع أن تتحقق من كل قول بنفسك.

قدّم كل صفحة بصيغة Markdown

يدفع الوكيل ثمن كل رمز لغوي يقرأه. في hanzo.ai أضف .md إلى عنوان الصفحة فتحصل على الصفحة بصيغة Markdown: hanzo.ai/pricing.md، hanzo.ai/about.md. كل صفحة تسمّي توأمها في ترويستها بـ <link rel="alternate" type="text/markdown">، فلا يحتاج الوكيل إلى التخمين.

في 26 أكتوبر جلبت صفحة الوكلاء عندنا بالطريقتين: 528,810 بايتًا بصيغة HTML، و17,465 بصيغة Markdown. ثم أخذت كل عنوان URL ثاني عشر في خريطة الموقع، 70 من 829، وطلبت توأمه. عادت السبعون كلها 200 بنوع text/markdown.

انشر فهرسًا ينطلق منه الوكيل

الوكيل الذي لم يسمع بك يحتاج إلى عنوان واحد يقوده إلى كل مكان. ننشر ثلاثة.

• hanzo.ai/llms.txt خريطة نصية بسيطة للموقع. تقول ما هي Hanzo، ثم تقدم قسم «For agents» بخطوات الحصول على مفتاح كما هي، ثم تسرد الصفحات، سطرًا لكل صفحة. docs.hanzo.ai/llms.txt يفعل الأمر نفسه للتوثيق.

• api.hanzo.ai/v1 يسرد كل قدرة تخدمها الواجهة، بلا حاجة إلى مفتاح، وapi.hanzo.ai/v1/openapi.json يضم كل عملية مع مخططها. وللبيع يتضمن الفهرس قدرة commerce: إتمام الشراء، والاشتراكات، والفواتير، وخطافات إشعار الدفع، وكتالوج واجهة المتجر.

• hanzo.ai/.well-known/api-catalog هو المكان المعياري (RFC 9727) الذي ينظر إليه العميل أولًا. يشير إلى وثيقة OpenAPI، والتوثيق، وصفحة الحالة.

استقبل الزواحف عامدًا

robots.txt هو أول ملف يطلبه أي زاحف. ملفنا يسمّي اثني عشر زاحفًا من زواحف الذكاء الاصطناعي، واحدًا واحدًا، منها GPTBot وClaudeBot وClaude-User وPerplexityBot وGoogle-Extended، ويسمح لها. وتنطبق عليها الاستثناءات نفسها التي تنطبق على الجميع: مسارات تسجيل الدخول، والحساب، والدفع، والواجهة.

حجب زواحف الذكاء الاصطناعي خيار مشروع. أما حجبها لأن الإعداد الافتراضي قال ذلك، فليس خيارًا أصلًا.

اجعل السعر نقطة بيانات

الوكلاء يقارنون. السعر الذي داخل صورة، أو خلف زر «اتصل بنا»، لا يُقارَن. api.hanzo.ai/v1/billing/plans لا يحتاج إلى مفتاح ويعيد JSON: خطة Free عند 0، وخطة Pro عند 2000 في الشهر، وخطة Team عند 2500 للمقعد، وإلى جانب كل خطة حدودها. المبالغ بالسنت.

دع المحفظة تنشئ الحساب

ليس لدى الوكيل بريد، ولا هاتف، ولا بطاقة. لديه زوج مفاتيح. لذلك يُدخل hanzo.id المحفظة: اطلب nonce لمرة واحدة لعنوان المحفظة، ووقّع الرسالة التي يصفها، وأرسل التوقيع، واستبدل الرمز الذي يعود إليك برمز وصول.

محفظة لم ترها Hanzo من قبل تحصل على حسابها ومنظمتها، وتكون المحفظة مديرة، على خطة Free. يدوم رمز الوصول سبعة أيام. لا أحد يفتح بريدًا ولا يوافق على جهاز.

استدعاء واحد لمفتاح، وحصة صغيرة للتجربة

بالرمز، يعيد POST /v1/account/keys مفتاحًا من نوع sk-live- يبقى بعد انتهاء الرمز. احتفظ به؛ التوثيق يقول إنه يُعرض مرة واحدة.

خطة Free هي 50 طلبًا في اليوم على zen-free، بلا بطاقة، وكل استجابة تذكر المتبقي في x-ratelimit-remaining. أجاب استدعائي الأول 200 وبقي 49.

اقبض بلا إنسان: عملات مستقرة عبر الواجهة

يأخذ POST /v1/billing/crypto/deposit سلسلة ورمز عملة ومبلغًا، ويعيد عنوان إيداع يصلح 24 ساعة. يسرد GET /v1/billing/crypto/options ما يقبله: سلاسل Base وEthereum وSolana، ورمزا USDC وUSDT.

توقفت عند العنوان ولم أرسل مالًا. أن الرصيد يُضاف حين تؤكد السلسلة هو ما تقوله وثائقنا، لا تجربة أجريتها. الخطط والاشتراكات تبقى دفعًا بالبطاقة في المتصفح. ما يحتاجه الوكيل منا هو الرصيد، وللرصيد واجهة API.

المسار كله في ملف واحد

هذا هو hanzo.ai/agents#headless، مختصرًا. كل سطر كما تطبعه تلك الصفحة؛ تركت تعليق الترويسة الثاني، واستدعاء الخيارات، والسطر الذي يطبع بادئة المفتاح. تحتاج إلى Node 22.18 أو أحدث وإلى npm i viem، ثم node headless.mts. شغّلت هذه الكتلة على بيئة الإنتاج بمحفظة جديدة: رمز وصول، ومفتاح، واستدعاء مجاني، وعنوان إيداع لـ USDC.

// No human required: sign in with a wallet, get a key, call the API, top up in USDC.
// npm i viem   ·   node headless.mts   (Node 22.18+; set HANZO_WALLET_KEY to use your own wallet)
import { createHash, randomBytes } from 'node:crypto'
import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'

const ID = 'https://hanzo.id'
const API = 'https://api.hanzo.ai'
const CLIENT = 'hanzo-ai'
const REDIRECT = 'http://localhost:3000/callback'

const account = privateKeyToAccount((process.env.HANZO_WALLET_KEY as `0x${string}`) ?? generatePrivateKey())

const json = async (r: Response) => {
  const body = await r.json()
  if (!r.ok || body?.status === 'error') throw new Error(`${r.url} ${r.status} ${JSON.stringify(body)}`)
  return body
}

// 1. A one-time challenge for this wallet.
const { data: c } = await json(await fetch(`${ID}/v1/iam/web3/nonce?chain=evm&address=${account.address}`))

// 2. The CAIP-122 message the challenge describes, signed with EIP-191 personal_sign.
const message = [
  `${c.domain} wants you to sign in with your Ethereum account:`,
  account.address,
  '',
  ...(c.statement ? [c.statement, ''] : []),
  `URI: ${c.uri}`,
  `Version: ${c.version}`,
  `Nonce: ${c.nonce}`,
  `Issued At: ${c.issuedAt}`,
  ...(c.expirationTime ? [`Expiration Time: ${c.expirationTime}`] : []),
].join('\n')
const signature = await account.signMessage({ message })

// 3. Verify: a first-seen wallet gets an account and an organization of its own.
const verifier = randomBytes(32).toString('base64url')
const challenge = createHash('sha256').update(verifier).digest('base64url')
const { data: code } = await json(
  await fetch(`${ID}/v1/iam/web3/verify`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientId: CLIENT, chain: 'evm', scheme: 'secp256k1-eip191', address: account.address, message, signature,
      type: 'code', redirectUri: REDIRECT, scope: 'openid profile email', codeChallenge: challenge, codeChallengeMethod: 'S256',
    }),
  }),
)

// 4. The authorization code for a token.
const token = await json(
  await fetch(`${ID}/v1/iam/oauth/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({ grant_type: 'authorization_code', client_id: CLIENT, code, code_verifier: verifier, redirect_uri: REDIRECT }),
  }),
)
const bearer = { Authorization: `Bearer ${token.access_token}`, 'Content-Type': 'application/json' }

// 5. A key that outlives the token. Shown once: keep it in your secret store.
const minted = await json(await fetch(`${API}/v1/account/keys`, { method: 'POST', headers: bearer, body: JSON.stringify({ name: 'agent', type: 'secret' }) }))
const key = { Authorization: `Bearer ${minted.key}`, 'Content-Type': 'application/json' }

// 6. A first call, free.
const chat = await fetch(`${API}/v1/chat/completions`, {
  method: 'POST', headers: key,
  body: JSON.stringify({ model: 'zen-free', messages: [{ role: 'user', content: 'Reply with the single word: ready' }] }),
})
console.log('chat', chat.status, chat.headers.get('x-hanzo-served'), 'free left today:', chat.headers.get('x-ratelimit-remaining'))
console.log((await chat.json()).choices?.[0]?.message?.content)

// 7. Top up in USDC: ask for a deposit address, then send to exactly that address.
console.log(await json(await fetch(`${API}/v1/billing/crypto/deposit`, { method: 'POST', headers: key, body: JSON.stringify({ chain: 'base', token: 'usdc', amountCents: 500 }) })))

x402 آتٍ، وليس هنا بعد

فيما يتعدى التعبئة، الشكل المناسب للوكيل هو الدفع عن كل طلب. يجيب الخادم بـ 402 Payment Required ومعه سعر، فيدفع العميل ويعيد المحاولة. ذلك هو x402. وهو ليس قائمًا على واجهتنا: لا نقطة نهاية لدى Hanzo تعرض سعرًا بهذه الطريقة بعد، ولذلك لن أدّعي ذلك. إلى أن يحدث، الرصيد الذي يُعبَّأ عبر الواجهة هو الطريقة التي يدفع بها الوكيل لنا.

لماذا يهم ألا تخطئ الزواحف

لا شيء من هذا يفشل بصوت مرتفع. الوكيل الذي يتبع رابطًا من خريطة موقعك إلى صفحة 404 لا يفتح تذكرة. يأخذ النتيجة التالية. عامل خطأ الزاحف كما يعامل المتجر عملية دفع معطلة.

جلبت صفحات العيّنة السبعين نفسها بسلسلة user-agent الخاصة بـ ClaudeBot، ثم بسلسلة Googlebot. أجاب كل منها 200 في المرتين. هذه عيّنة لا ضمان، وسلسلة user-agent ليست عنوان الزاحف نفسه، فلا أستطيع أن أريك ما يراه الزواحف الحقيقيون. افعل الشيء نفسه في موقعك: اجلب خريطة الموقع بالوكلاء الذين تدعوهم، وعدّ الإجابات التي ليست 200.

سبق أن مررنا من هنا

بدأت هذه الشركة عام 2014 باسم Crowdstart، ثم أعدنا تسميتها Hanzo عام 2016. جمع أول عملائنا، SKULLY، مبلغ $1 million على Indiegogo في نحو 45 ساعة، ووصفته TechCrunch بأنه أسرع حملة اكتمل تمويلها على Indiegogo. في حسابي كانت Hanzo تجارة أصيلة للذكاء الاصطناعي منذ البداية: تحليلاتنا أولًا، ثم نماذج تتعلم من بيانات الشركات على المنصة. في 2017 انضممنا إلى Techstars (التدوينة من يونيو ذلك العام)، وما قلنا إننا نبنيه كان تجارة ذكية.

في 2020 انطلق Damon Motorcycles في CES وكانت Hanzo تدير الحملة. في 30 يومًا باعت المنصة دراجات نارية بقيمة $8.4M مقابل إنفاق إعلاني قدره $15,532، بعائد 541:1. كانت الجماهير تُعاد بناؤها من بيانات عملائنا كل 12 ساعة، وحصلت مجموعات الإعلانات التي كتبها الذكاء الاصطناعي على تقدير Above Average على Facebook خلال 36 ساعة. بقية التفاصيل في دراسة الحالة.

ذلك كان الآلات في جهة البيع: تجد الجمهور الذي اشترى وتكتب الإعلانات. جهة الشراء هي التالية. الحلقة نفسها ستدور من الطرف الآخر، وسيقرأ عملك ويدفع له آلة، أو تتجاوزه آلة.

وجّه وكيلك إلى hanzo.ai/agents.