> For the complete documentation index, see [llms.txt](https://docs.goassay.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goassay.ai/developers/use-tools-get-started/how-paying-works.md).

# How paying works

Enable paid calls and understand what assay-mcp checks before signing each payment.

After you [install and sign in](/developers/use-tools-get-started/install-assay-mcp.md), free calls pass through to Assay. A paid call needs a payment key on your computer and spending permission approved by your wallet. Payments use **USDG** on **Robinhood Chain**.

Security model: Assay's servers never hold the private payment key; programs running as your OS user may be able to use it within its on-chain caps.

## Enable your first paid call

On the first paid attempt, `assay-mcp` creates the payment key locally, stores it in the OS keychain, and registers its public address with your agent's connection after proving ownership. The tool result returns an enable-paid link that ends in `#key=…`. Open it, fund the escrow if needed, and approve the key in your wallet. [Turn on paid calls](https://docs.goassay.ai/use-tools/turn-on-paid-calls) walks through each screen. Then ask your client to repeat the paid call; the setup attempt does not complete it.

{% hint style="danger" %}
The approval page shows a **Payment key** fingerprint: the last eight hexadecimal characters of the key's public address, in two groups. Approve only if it matches the fingerprint your client showed. If it differs, do not approve; reopen the link from your client.
{% endhint %}

To reopen the approval page after the first paid attempt, run:

```sh
npx -y @goassay-ai/mcp enable-paid
```

This command opens the link for an existing key; it does not create the key.

## What happens on each paid call

The client forwards the tool call. If Assay returns a payment request, `assay-mcp` checks it before signing. A failed or unreadable check means no payment signature.

| Check                            | What must be true                                                                                                                                                                                                           |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A real call is waiting           | The request answers a tool call just forwarded by this process and uses the supported payment format. The call has not been cancelled.                                                                                      |
| Correct destination and currency | The network, escrow destination, USDG asset and decimal precision match the built-in deployment. The amount is a valid positive amount.                                                                                     |
| Quoted price                     | A price quote exists for this tool in the same asset, and the requested amount is no higher than that quote.                                                                                                                |
| Authorized payer and key         | The payer matches the recorded account, if one is recorded. The chain confirms an active, unexpired permission for this computer's key. The server accepts that key's signature and names the same key.                     |
| Agreed chain state               | The built-in RPC endpoints agree. The chain read is recent enough; an unavailable, stale or conflicting read blocks signing.                                                                                                |
| Spending caps                    | The amount fits the key's and account's on-chain per-call caps, the local per-call cap, and the local total for the preceding 24 hours. The chain also enforces the on-chain spending-window caps when payment is redeemed. |
| Allowed provider and server      | The provider address is valid and passes any local provider restriction. Paid calls are allowed through this server URL; `/` is allowed by default after sign-in.                                                           |
| Valid request fields             | The sequence number, request hash, resource and timeout have valid formats and ranges. The resource names exactly the tool called, rather than another tool or an account debt operation.                                   |
| Confirmation, when enabled       | If the amount is above the local confirmation threshold, you approve that exact payment in the client. Confirmation is off by default.                                                                                      |

After the checks pass, the proxy records the amount against the local budget and signs an EIP-712 payment authorization. The signature covers the payer, provider, amount, tool resource, request hash, sequence and validity times, on the built-in chain and escrow contract. It sends the tool call again with that authorization attached.

It signs **at most one payment per tool call**. A second payment request for that call is returned unsigned.

## Check it worked

Your client returns the paid tool result without another setup link. A call outside the local limits is refused before signing.

## Errors

| Reason                          | Meaning                                                                 | Fix                                                                               |
| ------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Payment key mismatch            | The approval link does not name the key registered for this connection. | Do not approve; reopen the complete link from your client.                        |
| Chain state cannot be confirmed | The proxy cannot verify the key's permission.                           | Wait until the chain can be read and permission is confirmed before asking again. |
| Amount above a cap or quote     | The payment is outside an applicable bound.                             | Choose a tool within the default limits and its quoted price.                     |

## Go further

* Use tools: [Turn on paid calls](https://docs.goassay.ai/use-tools/turn-on-paid-calls)

## Next

* [Spending limits](/developers/use-tools-get-started/spending-limits.md)


---

# 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.goassay.ai/developers/use-tools-get-started/how-paying-works.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.