अपने AI एजेंट में भुगतान कैसे जोड़ें।
createClient को @agentcredia/node (या Python क्लाइंट) से एक एजेंट बनाएं, payments.create के साथ एक USDC भुगतान भेजें, और webhooks.verify के साथ हस्ताक्षरित वेबहुक को सत्यापित करें। खर्च नियंत्रण डैशबोर्ड में सेट किए जाते हैं और API के माध्यम से केवल पढ़ने के लिए होते हैं। एजेंट सीधे निजी कुंजियों को कभी नहीं छूता। साइन-अप से लेकर Base पर आपके पहले USDC भुगतान तक दस मिनट से कम, TypeScript या Python में।
शुरू करने से पहले।
- एक AgentCredia खाता (मुफ्त साइनअप).
- डैशबोर्ड से एक API कुंजी (इस गाइड के लिए
sk_test_कुंजी का उपयोग करें; आप बाद मेंsk_live_पर स्विच करेंगे)। - Node.js 20+ या Python 3.11+ आपके एजेंट रनटाइम में।
- किसी भी फ्रेमवर्क पर निर्मित एक एजेंट - LangChain, CrewAI, AutoGen, LlamaIndex, OpenAI Agents SDK, MCP, या साधारण SDK कोड। निर्देश फ्रेमवर्क-निषेधात्मक हैं।
- एक HTTPS एंडपॉइंट जो सार्वजनिक इंटरनेट से वेबहुक प्राप्त करने के लिए पहुंच योग्य है (विकास के लिए ngrok या एक डिप्लॉय पूर्वावलोकन ठीक है)।
एजेंट प्रोफ़ाइल बनाएं।
एजेंट प्रोफ़ाइल हर भुगतान के पीछे का पता लगाने योग्य पहचान है जो आपका एजेंट भेजता या प्राप्त करता है। इसमें वॉलेट पता, सार्वजनिक पृष्ठ, सत्यापन बैज, और (बाद में) व्यय नीति होती है। प्रत्येक तार्किक एजेंट के लिए एक बनाएं।
import { createClient } from "@agentcredia/node";
const client = createClient({ apiKey: process.env.AGENTCREDIA_API_KEY! }); // sk_test_ / sk_live_
const agent = await client.agents.create({ name: "research-bot" });
console.log(agent.id); // "agt_..."
// Public page: https://app.agentcredia.com/a/{slug}from agentcredia import Client
client = Client() # reads AGENTCREDIA_API_KEY from the environment
agent = client.agents.create(body={"name": "research-bot"})
print(agent["id"]) # "agt_..."
# Public page: https://app.agentcredia.com/a/{slug}After this call, the agent has a public page at https://app.agentcredia.com/a/<slug> that any counterparty (human or agent) can hover for verification info. See the agent payment identity glossary entry for what that page exposes.
भुगतान भेजें।
payments.create sends USDC from the agent wallet. amountWei is base units (USDC has 6 decimals), so 0.01 USDC is the string "10000". The SDK auto-stamps an Idempotency-Key, and the call can return 503 until the chain adapter is wired for your network. To RECEIVE instead, settle an invoice you created in the dashboard with paymentRequests.settle - see the payment API page.
// Send a USDC payment from the agent wallet. amountWei is base units
// (USDC has 6 decimals): "10000" is 0.01 USDC. payments.create auto-stamps an
// Idempotency-Key and can return 503 until the chain adapter is wired.
const tx = await client.payments.create({
agentId: agent.id,
to: "0xRecipient",
amountWei: "10000",
});
console.log(tx); // the submitted transfer# amountWei is USDC base units (6 decimals): "10000" is 0.01 USDC.
tx = client.payments.create(body={
"agentId": agent["id"],
"to": "0xRecipient",
"amountWei": "10000",
})
print(tx) # the submitted transferवेबहुक को संभालें।
वेबहुक यह बताते हैं कि भुगतान निपट गया है। Node में, @agentcredia/node से webhooks.verify HMAC जांच करता है और एक विभेदित संघ लौटाता है; अन्य भाषाओं में, कच्चे शरीर पर वही HMAC की गणना करें। घटना के प्रकार पर शाखा करें (इनबाउंड के लिए payment.received), जल्दी 2xx का उत्तर दें, और 2xx के पीछे भारी कुछ भी कतार में लगाएं ताकि डिलीवरी टाइम आउट न हो।
import express from "express";
import { webhooks } from "@agentcredia/node";
const app = express();
// Capture the RAW body. The HMAC is over the exact bytes on the wire.
app.use(express.raw({ type: "application/json" }));
app.post("/webhooks/payment", (req, res) => {
const result = webhooks.verify({
headers: req.headers,
rawBody: req.body, // Buffer, raw bytes
secret: process.env.AGENTCREDIA_WEBHOOK_SECRET!,
});
if (!result.ok) return res.status(400).json({ code: result.code });
if (result.eventType === "payment.received") {
// USDC landed - deliver the work, fulfil the order, etc.
void deliver(result.eventId);
}
res.status(200).send("ok");
});import hmac, hashlib, os, time
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["AGENTCREDIA_WEBHOOK_SECRET"].encode()
@app.post("/webhooks/payment")
def webhook():
raw = request.get_data() # RAW bytes - do not parse first
sig = request.headers.get("X-AgentCredia-Signature", "")
ts = request.headers.get("X-AgentCredia-Timestamp", "")
parts = dict(p.split("=", 1) for p in sig.split(",") if "=" in p)
t, v1 = parts.get("t", ts), parts.get("v1", sig)
want = hmac.new(SECRET, t.encode() + b"." + raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(want, v1) or abs(time.time() - int(t)) > 300:
abort(401)
if request.headers.get("X-AgentCredia-Event-Type") == "payment.received":
deliver(request.get_json()) # USDC landed
return ("ok", 200)डैशबोर्ड में खर्च नियंत्रण सेट करें।
If your agent only receives, you can skip this. If it also pays, set a spend permission - an allowance per period and a per-transaction cap - in the dashboard. It is enforced by the backend on every payment sent through the API, outside the agent's prompt, so prompt injection cannot rewrite it the way it can rewrite agent-side rules. There is no API or SDK call that mutates a permission (the agent's own key cannot widen its limit); the API is read-only, so your code can fetch the current values to display or plan around.
curl https://api.agentcredia.com/v1/agents/agt_123/spend-permissions \
-H "Authorization: Bearer $AGENTCREDIA_API_KEY"{
"allowance_wei": "5000000",
"per_tx_wei": "1000000",
"period_seconds": 86400,
"revoked_at": null
}Base Sepolia पर पूरे फ्लो का परीक्षण करें।
एक बार sk_live_ कुंजी पर स्विच करने से पहले, sk_test_ के साथ पूर्ण पथ को अंत से अंत तक चलाएँ। एक परीक्षण कुंजी सब कुछ Base Sepolia पर रखती है, जहाँ आप सार्वजनिक नल से वॉलेट को फंड करते हैं और प्रतिक्रिया आकार लाइव से मेल खाते हैं। कुंजी उपसर्ग नेटवर्क का चयन करता है, इसलिए एक परीक्षण कुंजी मेननेट फंड को स्थानांतरित नहीं कर सकती है।
तीन परिदृश्यों का अभ्यास करें: एक सुखद-मार्ग भुगतान जो payment.received को सक्रिय करता है, एक चूकी हुई डिलीवरी (वेबहुक को एक मृत URL पर इंगित करें, फिर transactions.get के साथ लेनदेन लाकर समायोजन करें), और एक वेबहुक पुनः प्रयास (पहली बार 500 लौटाएं, दूसरी बार 200, और पुष्टि करें कि आपका हैंडलर idempotent है)। जब सभी तीन परीक्षण पर पास हो जाएं, तो कुंजी बदलें और भेजें।
पांच गलतियाँ जो टीमों को एक सप्ताह का खर्च देती हैं।
वेबहुक हस्ताक्षर सत्यापन छोड़ना
यदि आप /webhooks/payment पर किसी भी POST को प्राधिकृत के रूप में स्वीकार करते हैं, तो एक हमलावर नकली भुगतान घटनाएँ बना सकता है और आपके एजेंट को मुफ्त में काम देने के लिए धोखा दे सकता है। हमेशा वेबहुक रहस्य के साथ HMAC-मान्य करें, एक स्थायी समय की तुलना का उपयोग करते हुए। पहला समझौता लगभग हमेशा गायब सत्यापन होता है।
एक अलग पुष्टि घटना मानते हुए
शिप किए गए इवेंट्स हैं payment.received, payment.sent, wallet.deployed, और webhook.test - कोई अलग पुष्टि इवेंट नहीं है। payment.received तब सक्रिय होता है जब हस्तांतरण एक ब्लॉक में होता है। अधिकांश कार्य के लिए, यह आपके लिए वितरित करने का संकेत है। कुछ महंगा या अपरिवर्तनीय के लिए, लेनदेन को transactions.get के साथ पोल करें और कार्य करने से पहले अपनी स्वयं की पुष्टि सीमा लागू करें; किसी ऐसे इवेंट का इंतजार न करें जो मौजूद नहीं है।
वेबहुक हैंडलर्स पर कोई आइडेम्पोटेंसी नहीं
Webhooks गैर-2xx प्रतिक्रियाओं पर पुनः प्रयास करते हैं, और वही घटना लोड के तहत कई बार आएगी। आपका हैंडलर आइडेम्पोटेंट होना चाहिए: उन इवेंट आईडी की एक छोटी तालिका रखें जिन्हें आपने पहले ही संसाधित किया है और डुप्लिकेट को छोड़ दें। अन्यथा एक क्षणिक ब्लिप एक ही कार्य को दो बार वितरित करेगा और आप डबल-फुलफिलमेंट को डिबग करने में घंटे बिता देंगे।
परीक्षण और लाइव API कुंजी मिलाना
परीक्षण कुंजियाँ (sk_test_) सैंडबॉक्स पर जाती हैं और Base Sepolia का उपयोग करती हैं; लाइव कुंजियाँ (sk_live_) उत्पादन पर जाती हैं और Base मेननेट का उपयोग करती हैं। पर्यावरण कॉन्फ़िग में उन्हें मिलाना अधिकांश 'डेव में काम करता है, प्रोड में विफल होता है' टिकटों का कारण है। यदि आपका रनटाइम वातावरण और कुंजी उपसर्ग मेल नहीं खाते हैं तो स्टार्टअप पर हार्ड-फेल करें।
एक गायब वेबहुक को एक विफल भुगतान के रूप में मानना
कोई विफलता घटना नहीं है, और एक वेबहुक छूट सकता है (आपका एंडपॉइंट डाउन था, एक डिलीवरी गिर गई)। एजेंट को 'फंड की प्रतीक्षा' लूप में अटका न छोड़ें। समेटें: वास्तविक स्थिति जानने के लिए transactions.get के साथ लेनदेन लाएँ, और किसी भी प्रतीक्षा प्रवाह पर समय सीमा रखें ताकि एक छोड़ी गई भुगतान संसाधनों को मुक्त कर दे जो हमेशा के लिए लटके न रहें।
जैसे ही आपके पास आपका पहला भुगतान होता है।
बुनियादी भुगतान कार्य करने के साथ, जो फॉलो-अप सबसे अधिक लाभ देते हैं वे हैं खर्च नियंत्रण (ताकि एजेंट बजट के साथ भाग न सके), वेबहुक मजबूती (ताकि भुगतान लोड के तहत चुपचाप न गिरें), और पहचान सत्यापन (ताकि प्रतिकृतियां एजेंट के सार्वजनिक पृष्ठ पर विश्वास करें)।
ऐसे एजेंट खर्च नियंत्रण स्थापित करें जो प्रॉम्प्ट इंजेक्शन से बच जाएं
वेबहुक पैटर्न जिनके बारे में डेवलपर्स सबसे अधिक पूछते हैं
GitHub और डोमेन सत्यापन बैज अर्जित करें
पूर्ण API संदर्भ docs.agentcredia.com पर है। समान APIs के लिए उत्पाद सतह: भुगतान API।