Skip to main content

AI Payment Protocol Overview

The AI Payment Protocol is a set of unauthenticated, protocol-oriented APIs designed to enable AI agents and autonomous clients to discover, negotiate, and execute payments on behalf of users.

Unlike the core merchant API which relies on server-side API keys, the AI Payment Protocol uses EIP-712 signatures for all state-changing operations, ensuring that the user explicitly authorizes every step of the payment flow.

Core Concepts​

1. EIP-712 Authorization​

All state-changing APIs (such as creating a session or preparing a payment) require an EIP-712 signature from the payer's wallet. This mechanism replaces traditional API keys and serves two purposes:

  1. Authentication: Verifies that the request comes from the payer address.
  2. Authorization: Ensures the user has explicitly agreed to the specific payment parameters (Amount, Token, Chain).

Every request body includes a message object and a signature string. The message must follow a specific EIP-712 type definition provided by the API in the previous step.

2. AI View​

Every API response includes an aiView object. This object is the "protocol view" of the current state, designed to be consumed by AI agents. It contains:

  • pricingModel: Describes how the price is calculated (e.g., "fixed").
  • workflow: Indicates the current stage of the transaction (e.g., link_ready, session_ready) and the allowed nextAction.
  • Requirements: Specific instructions for the next step, such as createPaymentSessionRequirement or preparePaymentRequirement. These objects provide the exact EIP-712 type definitions needed to construct the next request.

Protocol Workflow​

The typical lifecycle of an AI payment is:

  1. Discovery: The agent fetches a Payment Link (GET /payment/link/:id). The response contains the aiView with available supportedPaymentTokens and the create_payment_session signing requirement.
  2. Negotiation & Authorization: The agent presents the options to the user. The user selects a chain and token, and signs a create_payment_session message.
  3. Session Creation: The agent submits the signature to POST /payment/session/create to create a Payment Session.
  4. Preparation: The agent fetches the session state. If ready, the user signs a prepare_payment message to authorize the fund transfer.
  5. Execution: The agent submits the preparation signature to POST /payment/prepare. The server returns the raw blockchain calldata. The agent (or frontend) broadcasts this transaction to the blockchain.

Unified Error Handling​

All AI Payment APIs follow the platform's Unified Error Handling standard. Business logic errors will return HTTP 200 OK with a non-zero code field in the JSON body. Agents must check code === 0 to confirm success.