Authentifizierung und Scopes

Die Maschinen-Authentifizierung verwendet eine EIP-4361-SIWE-Challenge auf Flare mit chainId 14. Signiere exakt die zurückgegebene Nachricht mit deiner Wallet (EIP-191 personal_sign). Die Nonce ist einmalig, an die Wallet gebunden und läuft nach fünf Minuten ab. Fordere nur die benötigten Berechtigungen an. Das Beispiel fordert write und spend, weil die folgenden Auflade- und Abo-Beispiele beide verwenden; read ist immer enthalten.

curl -X POST 'https://ftso.app/api/x402/auth/challenge' \
  -H 'content-type: application/json' \
  -d '{"wallet":"0xYOUR_WALLET","scopes":["write","spend"],"label":"My agent"}'

Die Antwort enthält wallet, nonce, issuedAt und message. Bewahre message einschließlich Leerraum exakt auf. In viem nutzt du account.signMessage({ message }). Scopes sind Bestandteil der signierten Zustimmung; das Label ist kosmetische Metadaten mit höchstens 40 Zeichen. Rekonstruiere die Nachricht nicht aus der Nonce.

curl -X POST 'https://ftso.app/api/x402/auth/token' \
  -H 'content-type: application/json' \
  -d '{"message":"EXACT_RETURNED_SIWE_MESSAGE","signature":"0xSIGNATURE"}'
# Response: { token: "fbx_...", wallet, scopes, expiresAt }

Speichere token sicher und sende bei folgenden Aufrufen Authorization: Bearer fbx_…. Schreibe den Token nicht in Query-Strings, gemeinsam genutzte Logs oder Beispiele. Der Token-Austausch verwendet no-store. EOA-Signaturen werden lokal geprüft; die Prüfung von Contract-Wallets hängt vom konfigurierten Server-RPC ab und lehnt bei einem Prüffehler die Authentifizierung ab.

• read: Lesezugriffe und Nachrichtenvorschau; umfasst bezahlten Datenzugriff, falls Enforcement aktiviert wird.
• write: Änderungen, Empfängertests, Auflade-Drafts und Bestätigungen, Zustimmung zu Bedingungen, Tests und Abschalten von Auto-Renew.
• spend: Kauf von Abo-Kapazität und Einschalten von Auto-Renew.
• read wird immer erteilt, auch mit write oder spend. Ein write-Token kann jeden Token derselben Wallet widerrufen.

curl 'https://ftso.app/api/x402/auth/tokens' -H 'authorization: Bearer fbx_TOKEN'
curl -X DELETE 'https://ftso.app/api/x402/auth/tokens/42' \
  -H 'authorization: Bearer fbx_WRITE_TOKEN'

Eine Wallet darf höchstens zehn aktive Token haben. Die Liste liefert bis zu 50 Metadateneinträge, aktive zuerst; Secrets oder Hashes werden nie zurückgegeben. Der Widerruf wirkt beim nächsten authentifizierten Aufruf. Fremde IDs liefern 404. Im Browser lassen sich Token unter Wallet-Center Settings → Security verwalten. MCP nutzt einen eigenen OAuth-Ablauf; ein x402-Bearer-Token ist kein MCP-Access-Token.

• Gültigkeit des Bearer-Tokens in Sekunden: 86400
• Kostenlose anonyme Aufrufe pro Tag (nur enforce): 50