Skip to main content
Ein Agent mit einem API-Schlüssel kann alles ausgeben, was der Schlüssel ausgeben kann. Das ist in Ordnung, wenn eine Person zusieht, und heikel, wenn niemand hinschaut. Die üblichen Lösungen leben außerhalb des Agenten, in einem Dashboard oder einer Abrechnungswarnung, die dir vom Problem erzählt, nachdem es passiert ist. Venice unterstützt einen zweiten Weg hinein. Statt eines Schlüssels hält der Agent ein Wallet. Er authentifiziert sich, indem er eine Nachricht signiert, zahlt jede Anfrage aus einem USDC-Guthaben, das an diese Wallet-Adresse gebunden ist, und jede Belastung landet in einem Ledger, den er zurücklesen kann. Es gibt kein Konto, kein Dashboard und keinen Schlüssel, der geleakt werden kann. Die Obergrenze ist das Guthaben, und du entscheidest, was du dort hineinlegst. Diese Anleitung baut einen Agenten, der genau das tut, unter einem Budget, das er sich selbst auferlegt.

Führ dieses Notebook in Google Colab aus

Jeder Schritt unten als ausführbares Notebook. Es läuft ohne finanziertes Wallet und stoppt an der Zahlungswand, sodass du den ganzen Ablauf sehen kannst, bevor du etwas ausgibst.

Wie es funktioniert

Vier bewegliche Teile, drei davon sind einfach HTTP: Die Inferenz selbst ist der gewöhnliche /chat/completions-Aufruf. Der einzige Unterschied ist, welchen Header du sendest.

Was der Start kostet

Zwei Zahlen sind wichtig, und sie sind nicht dieselbe Zahl. Der Mindest-Top-up beträgt fünf Dollar. Das ist der kleinste Betrag, den /x402/top-up abwickelt, und er wird in der Discovery-Antwort zurückgegeben, nicht irgendwo hardgecodet — lies ihn also, statt dieser Seite zu vertrauen. Das Mindestguthaben, um einen Aufruf zu tätigen, sind zehn Cent. Ein Wallet mit weniger bekommt von der Inferenz ein 402 zurück, obwohl es Geld hält. Fünf Dollar sind also das kleinste Wallet, das sich zu finanzieren lohnt, und fünf Dollar sind das, was diese Anleitung dem Agenten mitgibt. Es lohnt sich zu wissen, was das kauft: Eine kurze Frage an qwen3-5-9b kostet etwa 27 Input-Tokens und 26 Output-Tokens, was zu den Preisen dieses Modells ungefähr sieben Millionstel Dollar entspricht. Fünf Dollar sind in der Größenordnung von dreiviertel Millionen Fragen. Das Budget hier ist keine enge Beschränkung, es ist ein Explosionsradius.

Setup

Das x402-SDK erledigt das Zahlungssignieren. Bau das nicht selbst nach: Die Transfer-Autorisierung ist EIP-712-typisierte Daten, und ein wiederverwendeter Nonce scheitert bei der Verifikation auf mühsam zu debuggende Weise.
Das x402-Python-SDK benötigt Python 3.10 oder neuer. Colab passt. Ein System-Python, das mit macOS geliefert wurde, vielleicht nicht.
Erstelle agent.py mit der Konfiguration. BUDGET_USD ist die Obergrenze, die der Agent sich selbst auferlegt, hier auf das gesamte Wallet gesetzt. Senk sie ab, und der Agent stoppt, bevor das Geld ausgeht — das ist der einzige Regler, den du wahrscheinlich anfassen wirst.

Ein Wallet, das der Agent besitzt

Der Agent braucht ein Schlüsselpaar. In der Produktion ist das ein Wallet, das du bewusst finanziert hast und dessen Schlüssel in einem Secret-Manager lebt. Während du baust, ist das Erzeugen eines Wegwerf-Wallets die richtige Bewegung, denn ein Wallet ohne Geld kann versehentlich nichts Teures tun.
Halte den privaten Schlüssel aus dem Notebook heraus. In Colab leg ihn in Secrets ab und lies ihn mit userdata.get("WALLET_KEY").

Signieren statt Authentifizieren

Es gibt keinen Schlüssel zum Senden, also trägt jede Anfrage einen Beweis, dass der Wallet-Besitzer sie gestellt hat. Der Beweis ist eine EIP-4361-Nachricht, signiert und dann base64-kodiert in den SIGN-IN-WITH-X-Header. Das Nachrichtenformat ist exakt. Venice baut diese Bytes auf seiner Seite neu auf und verifiziert deine Signatur dagegen, sodass eine verirrte Leerzeile eine abgelehnte Signatur bedeutet statt einer hilfreichen Fehlermeldung.
Drei Regeln bestimmen diese Header, und alle drei existieren, um Replays zu verhindern. Die Signatur ist ab Issued At fünf Minuten lang gültig. Jeder Nonce ist etwa fünfeinhalb Minuten lang einmal verwendbar. Und der Signierer muss zum Wallet im Pfad passen, sodass ein Wallet kein anderes einsehen kann und beim Versuch ein 403 bekommt. Die praktische Konsequenz ist, dass du pro Anfrage einen frischen Header signierst, statt einen zu cachen. Signieren ist lokal und gratis, das kostet also nichts.
Auf einem frischen Wallet:
canConsume ist das Feld, auf das du verzweigen solltest. Es berücksichtigt die Zehn-Cent-Untergrenze, damit du das nicht tun musst.

Geld einzahlen

Ein Top-up sind zwei Anfragen. Die erste fragt, was Venice akzeptiert, und ist nicht authentifiziert, weil es noch nichts zu authentifizieren gibt. Die zweite trägt eine signierte Transfer-Autorisierung.
Discovery gibt einen Eintrag pro Rail zurück. Heute Base und Solana:
Zwei Details darin sind leicht zu übersehen. amount ist in Basiseinheiten, und USDC hat sechs Dezimalstellen, also sind 5000000 fünf Dollar und keine fünf Millionen von irgendetwas. Auf dem Solana-Rail ist extra.feePayer ein von Venice betriebenes Konto, das die Transaktionsgebühr trägt, wodurch ein Wallet zahlen kann, ohne SOL zu halten.
Die Standard-Ausgabensteuerung ist das Erste, was dich stoppen wird. Das SDK wird mit max_amount_per_payment auf einen Dollar ausgeliefert, und der Venice-Mindest-Top-up beträgt fünf, sodass ein unveränderter Client jede angebotene Rail ablehnt und NoMatchingRequirementsError wirft, bevor er überhaupt das Netzwerk kontaktiert. Heb die Grenze bewusst an, statt die Ausgabensteuerung abzuschalten.
Ein Settlement aus einem Wallet ohne USDC gibt ein 400 mit PAYMENT_VERIFICATION_FAILED zurück. Das ist die erwartete Form des Fehlschlags: Die Signatur war in Ordnung, der Transfer nicht.

Pro Aufruf bezahlen

Mit einem Guthaben in place ist Inferenz eine normale Anfrage, die zufällig eine Signatur trägt. Den Venice-System-Prompt abzuschalten ist wichtiger, als es aussieht: Er ist etwa siebzehnhundert Input-Tokens pro Aufruf wert, was zwei Größenordnungen mehr ist als die Frage selbst.
402 als normalen Ausgang zu behandeln statt als Ausnahme ist der ganze Entwurf. Ein Agent, der sich selbst bezahlt, wird irgendwann kein Geld mehr haben, und kein Geld mehr zu haben ist kein Crash.

Auslesen, was er ausgegeben hat

Der Ledger ist maßgeblich. Frag lieber, was tatsächlich in Rechnung gestellt wurde, als aus Token-Zählern zu schätzen.
Jede Zeile verweist zurück auf den Aufruf, der sie verursacht hat:
TOP_UP- und REFUND-Zeilen tauchen hier auch auf, mit positiven Beträgen. Auf CHARGE zu filtern liefert dir die Ausgaben.

Der budgetierte Lauf

Jetzt die Schleife. Vor jedem Aufruf prüft der Agent, was er ausgegeben hat, und lehnt Arbeit ab, die er nicht bezahlen kann.
Führ es mit den vollen fünf Dollar aus, und das Budget greift nie — das ist das ehrliche Ergebnis bei diesen Preisen. Um zu sehen, wie die Obergrenze tatsächlich arbeitet, setz eine, die schon ein einzelner Aufruf überschreitet:

Wo dich das hinterlässt

Der Agent hält sein eigenes Geld, weist seine Identität mit einer Signatur nach und kann kein Limit überschreiten, das du setzt — und das alles, ohne dass irgendwo ein Konto existiert. Für einen geplanten Job, eine Serverless-Function oder alles andere, dem du ungern einen langlebigen Schlüssel in die Hand drückst, ist das eine wesentlich andere Sicherheitslage. Ein paar Dinge, die sich als Nächstes lohnen:

Im Protokoll begrenzen

Ausgabensteuerungen im SDK gelten pro Zahlung, nicht pro Session. Kombiniere sie mit der Budget-Schleife oben, damit ein Bug in dem einen den anderen nicht aushebeln kann.

Bei Leerstand auffüllen

Fang das 402 ab, füll auf und wiederhole. Genau das erledigt venice-x402-client auf der TypeScript-Seite für dich.

Auf Solana zahlen

Derselbe Ablauf, andere Rail. Signiere Ed25519 und setze den zurückgegebenen feePayer, sodass das Wallet kein SOL braucht.

Gib ihm echte Arbeit

Tausch die Aufgabenliste gegen eine Tool-Calling-Schleife, und der Ledger fängt an, dir zu zeigen, was jede Entscheidung gekostet hat.
Für die vollständige Endpunkt-Referenz siehe x402 top-up und x402 mit der Venice-API verwenden.