X402 `exact` und `upto` Abrechnungsmodelle

Ace Data Cloud X402 verwendet derzeit zwei Arten von Modellen: exact und upto. Sie lösen unterschiedliche Abrechnungsprobleme.

`exact`

exact bedeutet, dass der Preis vor dem Zugriff auf die Ziel-API festgelegt werden kann. Der vom Client signierte Betrag ist der endgültige Abhebungsbetrag. Geeignet für:

Festpreis-Bilderzeugung;
Festpreis-Videoprojekt-Erstellung;
Festpreis-Such- oder Tool-APIs;
Bestellzahlungen.

EVM exact verwendet USDC EIP-3009 TransferWithAuthorization:

{
  "x402Version": 2,
  "accepted": {
    "scheme": "exact",
    "network": "eip155:8453"
  },
  "payload": {
    "authorization": {
      "from": "0x...",
      "to": "0x...",
      "value": "95215",
      "validAfter": "1780237345",
      "validBefore": "1780240945",
      "nonce": "0x..."
    },
    "signature": "0x..."
  }
}

Der Facilitator überprüft in der Phase /verify die Signatur und den Betrag und reicht in der Phase /settle diese Genehmigung auf der Blockchain ein.

`upto`

upto bedeutet, dass der Client einen maximalen Betrag genehmigt, und Ace Data Cloud nach Abschluss der Anfrage basierend auf dem tatsächlichen Verbrauch abrechnet, wobei der tatsächliche Abhebungsbetrag den Höchstbetrag nicht überschreiten darf. Geeignet für:

Chat-Vervollständigung: Der endgültige Preis hängt von den Prompt-Tokens und Completion-Tokens ab;
Streaming-Antworten: Die tatsächliche Ausgabelänge wird erst nach Abschluss bekannt;
Zukünftige nachgelagerte Abrechnungs-APIs.

upto verwendet Permit2 PermitWitnessTransferFrom. Der vom Client signierte Betrag ist keine feste Überweisung, sondern eine Genehmigung mit Zeugen für einen Höchstbetrag:

{
  "x402Version": 2,
  "accepted": {
    "scheme": "upto",
    "network": "eip155:8453"
  },
  "payload": {
    "permit2Authorization": {
      "from": "0x...",
      "spender": "0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002",
      "nonce": "123456789",
      "deadline": "1780240945",
      "permitted": {
        "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "amount": "95215"
      },
      "witness": {
        "to": "0x...",
        "facilitator": "0x...",
        "validAfter": "1780237345"
      }
    },
    "signature": "0x..."
  }
}

permitted.amount ist der Höchstbetrag, der nicht unbedingt der endgültige Abhebungsbetrag ist. Der Gateway wird in der Phase /record den tatsächlichen Verbrauch in amount umwandeln und an den Facilitator übermitteln. Der Facilitator darf nur amount <= permitted.amount abrechnen. Das Ergebnis der Basis upto-Programm-Ausführung:

payer 0x5d4f08D5c2bb60703284bc06671Eb680fA41B105
elapsed_ms 5104
content ADC_BASE_UPTO_OK
id chatcmpl-DlcbyS4IT8kUAMo4Ri97HiIHc9T8V
tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
block 46726437
explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
signed ceiling 95215 atomic USDC
transfer value 3 atomic USDC

Erläuterung:

Der in 402 zurückgegebene Genehmigungsobergrenze beträgt 95215 atomic USDC, der Client signiert mit diesem Höchstbetrag.
Nach der tatsächlichen Antwort des Modells wird nur 3 atomic USDC abgerechnet, die Blockchain-Transaktion kann auf BaseScan eingesehen werden.
Dieses Ergebnis verdeutlicht den entscheidenden Unterschied von upto: Der signierte Betrag ist die Obergrenze, die Blockchain-Abrechnung kann unter der Obergrenze liegen.
Wenn der tatsächliche Verbrauch die Obergrenze überschreitet, sollte der Facilitator die Abrechnung ablehnen, und der Client muss eine neue Genehmigung mit einer höheren Obergrenze erteilen.

upto wird derzeit nur auf Base angeboten. SKALE bietet nur exact an. Wenn Sie nachgelagerte Abrechnung benötigen, verwenden Sie bitte Base.

Warum ist Permit2 genehmigen erforderlich

upto wird letztendlich von x402 Proxy über Permit2 aus der Zahlung Brieftasche USDC abrufen. Vor der ersten Verwendung muss die Zahlung Brieftasche Permit2 einmal eine ERC-20 Genehmigung erteilen. Python CLI:

pip install 'acedatacloud-x402[cli]'
X402_PRIVATE_KEY=0x... acedatacloud-x402 approve-permit2 --network base

Programmierschnittstelle:

from acedatacloud_x402 import EVMAccountSigner, approve_permit2

approve_permit2(
    rpc_url="https://mainnet.base.org",
    signer=EVMAccountSigner.from_private_key("0x..."),
    token_address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
)

Nach Abschluss der Genehmigung muss bei jeder Anfrage weiterhin ein neues upto-Envelope signiert werden, da nonce, deadline, witness und Höchstbetrag unterschiedlich sind.

Nullbetrag-Abrechnung

upto unterstützt den Fall, dass der tatsächliche Betrag 0 beträgt. Beispielsweise, wenn die Ziel-API keine abrechnungsfähige Menge erfolgreich erzeugt hat, kann der Gateway amount = "0" übermitteln. Der Facilitator wird erfolgreich zurückgeben, aber keine Blockchain-Transaktion durchführen. Dies kann das Problem vermeiden, dass “Anfragen nicht erfolgreich sind, aber dennoch Gebühren auf der Blockchain abgebucht werden”.

Auswahlempfehlungen

Szenario	Empfehlung
Festpreis-API	Verwenden Sie `exact`, die Logik ist einfach.
Bestellzahlung	Verwenden Sie `exact`.
Chat-Vervollständigung, nach Token abrechnen	Verwenden Sie Base `upto`.
Noch keine Permit2 Genehmigung	Zuerst `exact` verwenden, dann auf `upto` umstellen.
Benötigen Sie nachgelagerte Abrechnung auf SKALE	Derzeit nicht unterstützt, SKALE bietet nur `exact`.

Wenn Sie sich nicht sicher sind, welches Sie wählen sollen, verwenden Sie zunächst das Standardverhalten des SDK; das SDK wählt die vom Server zurückgegebene passende Netzwerk-Zahlungsanforderung.

Base `upto` Prüfcheckliste

Bei der Integration oder Fehlersuche stellen Sie bitte sicher, dass die folgenden Parameter aus derselben 402-Antwort stammen und bei der Client-Signatur konsistent bleiben:

Parameter	Prüfpunkt
`network`	Muss `eip155:8453` sein.
`scheme`	Muss `upto` sein.
`extra.chainId`	Die Base-Chain-ID ist `8453`.
`asset`	Verwenden Sie die Base USDC Vertragsadresse aus der 402-Antwort.
`extra.facilitatorAddress`	Muss am Zeugen teilnehmen und mit dem Facilitator `/supported` übereinstimmen.
Permit2 Genehmigung	Die Zahlung Brieftasche muss zuvor Permit2 für Base USDC genehmigen.

Häufige Fehler und deren Behebung:

Fehler	Behebung
`invalid_upto_evm_payload_invalid_signature`	Überprüfen Sie, ob die Chain-ID, die Facilitator-Adresse, die Permit2-Domain, der Spender, das signierende Konto und der Zeuge mit der 402-Antwort übereinstimmen.
`PERMIT2_ALLOWANCE_REQUIRED`	Führen Sie nach der Genehmigung von Permit2 für die Ziel-Chain USDC die Anfrage erneut durch.
`amount exceeds permitted amount`	Der tatsächliche Verbrauch überschreitet die signierte Obergrenze, eine neue Genehmigung mit einer höheren Obergrenze ist erforderlich.

Erste Schritte

KI Chat

KI Bild

KI Video

KI Audio

Web & Daten

CAPTCHA

Identität

Coding

Weitere Anleitungen

X402 `exact` und `upto` Abrechnungsmodelle

`exact`

`upto`

Warum ist Permit2 genehmigen erforderlich

Nullbetrag-Abrechnung

Auswahlempfehlungen

Base `upto` Prüfcheckliste

​exact

​upto

​Warum ist Permit2 genehmigen erforderlich

​Nullbetrag-Abrechnung

​Auswahlempfehlungen

​Base upto Prüfcheckliste

`exact`

`upto`

Warum ist Permit2 genehmigen erforderlich

Nullbetrag-Abrechnung

Auswahlempfehlungen

Base `upto` Prüfcheckliste