> For the complete documentation index, see [llms.txt](https://docs.toolkit.equs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toolkit.equs.ai/docs/agentic/ap2.md).

# Agentic Payments (AP2)

Let an AI agent act for a User within bounds they approved - and prove it, with AP2 mandates signed in the User's own wallet

**AP2, the** [**Agent Payments Protocol**](https://ap2-protocol.org/), is an open protocol for payments that AI agents start. Its premise is simple: a merchant or payment provider can't act on *"the agent says the User wanted this"*. The authorization has to arrive as something they can verify.

AP2 calls that something a **mandate**: a signed, tamper-evident credential in which the User either approves one concrete purchase, or sets bounds within which a named agent may buy later, on its own. Every later action by the agent traces back to something the User actually signed.

The platform provides the **User-approval side** of AP2: putting a mandate in front of the User in their wallet, verifying what comes back, and - if the platform hosts your agent's wallet - turning an approved mandate into concrete signed artifacts when the agent is ready to buy. **Executing the payment is not part of it**: the platform produces the authorization and hands it to your agent.

Mandates are built on [Delegation](/docs/agentic/delegation.md): each is a hop the User signs on top of a credential they already hold. You never build the hop yourself - you describe the mandate, and the platform turns it into the request the wallet signs.

{% hint style="info" %}
The User approves in their own wallet - the EQUS Wallet, or any wallet that can sign a delegation - and must already hold a credential that satisfies your VP Schema: the mandate is signed over that credential.
{% endhint %}

## Key terms

| Term               | Meaning                                                                                                           |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| **Mandate**        | What the User approves. Its type (`vct`) says which kind                                                          |
| **Open mandate**   | Bounds the User sets for a purchase the agent makes later - which items, which merchants, how much                |
| **Closed mandate** | One concrete checkout or payment. Signed by the User when they're present, or by the agent when it closes a grant |
| **Grant**          | The signed result of approving Open mandates, bound to the agent's key                                            |
| **Closing**        | Turning a grant into Closed mandates for one concrete checkout, signed with the agent's key                       |
| **`requestUri`**   | The request to hand to the User's wallet - as a QR code, a link or a redirect                                     |
| **`txId`**         | Identifies the request. You need it later to collect and verify the User's response                               |

## How it works

The common case is **Human not present**: the User approves bounds once, and the agent buys later without asking again.

```mermaid
sequenceDiagram
    autonumber
    actor U as User
    participant W as User's wallet
    participant A as Your agent
    participant P as Platform
    participant M as Merchant

    Note over U,M: The User sets the bounds
    A->>P: Open mandates - Red Sneakers, up to USD 500<br/>plus the agent's public key
    P->>A: mandate request - requestUri, txId
    A->>W: show the request to the User
    U->>W: approve the bounds
    W->>P: the mandates, signed by the User<br/>over their credential
    A->>P: collect and verify the User's response
    P->>A: the grant - the User's signed mandates,<br/>bound to the agent's key

    Note over U,M: Later, with the User elsewhere
    A->>M: shop within the bounds
    M->>A: checkout, signed by the merchant
    A->>A: close the grant - sign Closed mandates<br/>for this checkout and payment
    Note over A,P: on Flows 2 and 3, the platform signs for your agent
    A->>M: Closed mandates - the grant plus<br/>this checkout and payment
    M->>M: check the signatures back to the User's credential,<br/>and that the purchase fits the bounds
    Note over A,M: payment happens outside the platform
```

## Human present or not

|                         | Human not present                                                     | Human present                                       |
| ----------------------- | --------------------------------------------------------------------- | --------------------------------------------------- |
| **The User approves**   | Bounds for a future purchase - which items, which merchants, how much | One concrete checkout and payment, now              |
| **Mandates**            | Open: `mandate.checkout.open.1`, `mandate.payment.open.1`             | Closed: `mandate.checkout.1`, `mandate.payment.1`   |
| **Agent key**           | Required - only that agent can act on the mandate                     | Not allowed - nothing is delegated                  |
| **What the agent gets** | A grant, which it later closes into Closed mandates                   | The Closed mandate itself, ready to show a merchant |

Open and Closed mandates can't be mixed in one request. The platform implements AP2's *User credential* trust model: the merchant trusts the Issuer of the User's credential, and every mandate chains back to it.

## Choose a flow

All three flows put the same mandate in front of the User. What differs is **where your agent's wallet lives** and, when the platform hosts it, **who signs in to use it**. That decides who holds the key, who stores the grant, and who signs the Closed mandates.

|                     | Flow 1 - Your Own Agent Wallet     | Flow 2 - User Acts for Their Agent           | Flow 3 - Agent Uses Its Own Token            |
| ------------------- | ---------------------------------- | -------------------------------------------- | -------------------------------------------- |
| **Agent key**       | Yours; only the public key is sent | Generated and held by the platform           | Generated and held by the platform           |
| **Grant**           | Yours to store                     | Stored by the platform, in the agent's vault | Stored by the platform, in the agent's vault |
| **Closing**         | Yours to sign                      | One platform call                            | One platform call                            |
| **Calls made with** | Your Tenant token                  | The User's wallet token, naming the agent    | The agent's own token                        |
| **Calls on**        | Integration API                    | Web Custodial Wallet API                     | Web Custodial Wallet API                     |
| **Status**          | Available                          | Experimental, on request                     | Experimental, on request                     |

Flow 1 has two methods, as for Presentation: **Embed UI + API**, where Embed UI opens the User's wallet over your page, and **Build Your Own UI**, where the screens are yours. Flows 2 and 3 hand the request to the User the same way.

## Before you start

1. **A Verifier and a VP Schema**, set up as in [Configuration](/docs/presentation/configuration.md). The VP Schema must declare **exactly one** credential input - AP2 requests reject anything else. Which credential you ask for is yours to choose: the mandate travels with the request, not in the schema.
2. **For Flows 2 and 3**, an agent on the platform - see [Flow 2](/docs/agentic/ap2/flow-2.md) and [Flow 3](/docs/agentic/ap2/flow-3.md).

## Known limitations

* **No status lookup.** Keep your own record of every `txId`. There is no call to list requests, check whether one has been answered, or cancel one.
* **The platform doesn't check Closed content against the Open bounds.** It enforces that a checkout and its payment link up, but whether the Closed content stays inside what the User approved is for whoever verifies the artifact - the merchant or payment provider - to check. Your agent should check it too before closing, so its artifacts aren't rejected.
* **Delivery is yours.** The platform doesn't forward, verify or store the Closed mandates it returns, and doesn't validate the audience you give them.
* **No revocation.** An approved grant can't be revoked; its window is its `exp` - one hour by default.
* **AP2 is at v0.2.** `vct` values and constraint shapes may change with the specification.

## Where to next

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3><i class="fa-key" style="color:$primary;">:key:</i></h3></td><td><strong>Flow 1: Use Your Own Agent Wallet</strong></td><td>Your agent keeps its own key and grant; the platform asks the User and verifies.</td><td><a href="/docs/agentic/ap2/flow-1.md">Flow 1: Use Your Own Agent Wallet</a></td></tr><tr><td><h3><i class="fa-user" style="color:$primary;">:user:</i></h3></td><td><strong>Flow 2: User Acts for Their Agent</strong></td><td>The platform hosts your agent's wallet; calls go with the User's own token.</td><td><a href="/docs/agentic/ap2/flow-2.md">Flow 2: User Acts for Their Agent</a></td></tr><tr><td><h3><i class="fa-robot" style="color:$primary;">:robot:</i></h3></td><td><strong>Flow 3: Agent Uses Its Own Token</strong></td><td>The platform hosts your agent's wallet; the agent signs in on its own.</td><td><a href="/docs/agentic/ap2/flow-3.md">Flow 3: Agent Uses Its Own Token</a></td></tr><tr><td><h3><i class="fa-book" style="color:$primary;">:book:</i></h3></td><td><strong>Mandate Reference</strong></td><td>Mandate types, constraints, validation rules and error codes.</td><td><a href="/docs/agentic/ap2/mandate-reference.md">Mandate Reference</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.toolkit.equs.ai/docs/agentic/ap2.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.