> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Payments

> Let your agent top up its own TinyFish wallet with the Machine Payments Protocol (MPP)

When your agent runs low on credit, it can add money to your TinyFish wallet itself and keep working. It pays with the wallet it already has, over the [Machine Payments Protocol (MPP)](https://mpp.dev/overview), the open standard Stripe and Tempo created for agents paying over HTTP. No dashboard needed. Whether you approve each payment is up to your wallet: some, like Stripe's Link agent wallet, ask you to approve each one.

<Note>
  Agent payments are rolling out gradually, and need an account on wallet billing. If `POST /v1/wallet/top-up` answers `404` with `FEATURE_NOT_AVAILABLE`, they aren't available for your account yet.
</Note>

## How It Works

1. Your agent asks TinyFish to top up, say \$25.
2. TinyFish answers with an HTTP `402` payment challenge: the amount, the currency, and who to pay.
3. Your agent's wallet issues a one-time [Shared Payment Token (SPT)](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens) for that amount. Your card details never reach the agent or TinyFish.
4. Your agent retries with the payment, Stripe charges it, and your wallet is credited in seconds, with a receipt.

Any wallet that speaks MPP with the `stripe` payment method works, including Stripe's [Link agent wallet](https://docs.stripe.com/agentic-commerce/link-agent-wallet).

| Detail | Value |
| - | - |
| Amount per top-up | $10.00 to $500.00, in whole cents |
| Currency | USD |
| Payment method | Card, through a Stripe Shared Payment Token |
| Where | REST API and the TinyFish MCP server |

***

## REST API

Top-ups use your normal API key in the `X-API-Key` header. The payment travels in a separate `Payment-Authorization` header.

<Tip>
  `GET /v1/wallet` includes `agent_top_up_url` when agent payments are available for your account, so an agent checking its balance can find the endpoint.
</Tip>

<Steps>
  <Step title="Ask for a top-up">
    ```bash theme={null}
    curl -i -X POST https://agent.tinyfish.ai/v1/wallet/top-up \
      -H "X-API-Key: $TINYFISH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"amount": "25.00"}'
    ```

    The response is `402 Payment Required` with the challenge in the `WWW-Authenticate` header:

    ```
    WWW-Authenticate: Payment id="…", realm="agent.tinyfish.ai", method="stripe", intent="charge", request="…", expires="…", header="Payment-Authorization"
    ```
  </Step>

  <Step title="Pay the challenge">
    Hand the challenge to your MPP wallet. Once the payment is approved (some wallets, like Link, ask you first), it returns a payment credential (`Payment <base64url>`). The challenge expires after 30 minutes, which leaves time for that approval.
  </Step>

  <Step title="Retry with the payment">
    Send the same request again, with the same amount, plus the credential:

    ```bash theme={null}
    curl -X POST https://agent.tinyfish.ai/v1/wallet/top-up \
      -H "X-API-Key: $TINYFISH_API_KEY" \
      -H "Payment-Authorization: Payment eyJjaGFsbGVuZ2Ui…" \
      -H "Content-Type: application/json" \
      -d '{"amount": "25.00"}'
    ```
  </Step>
</Steps>

MPP clients that handle `402` responses, such as Stripe's Link agent wallet, run steps 2 and 3 for you.

### Responses

| Status | Meaning | What your agent should do |
| - | - | - |
| `200` | Paid and credited. `available_balance` is your new balance (or `null` if it couldn't be read). | Carry on. |
| `202` | Paid, and the credit lands within minutes. | Don't pay again. Check the balance shortly. |
| `402` with `WWW-Authenticate` | No payment was sent. This is the challenge. | Pay it and retry. |
| `402` without `WWW-Authenticate` | A payment was sent but not accepted. `detail` says why. | Don't pay again on your own (see below). |
| `400` | The amount is invalid or outside $10 to $500. | Fix the amount. |
| `404` | Agent payments aren't available for your account. | Top up from the [dashboard](https://agent.tinyfish.ai) instead. |

A successful top-up looks like this:

```json theme={null}
{
  "status": "settled",
  "amount": "25.00",
  "currency": "USD",
  "payment_reference": "pi_3QxYz2Ab",
  "available_balance": "31.44"
}
```

The response also carries an MPP `Payment-Receipt` header.

***

## MCP

If your agent connects to the TinyFish MCP server at `https://agent.tinyfish.ai/mcp` (see [MCP Integration](/mcp-integration)), it gets a `top_up_wallet` tool. It needs no API key: it tops up the wallet of the account you signed in with.

The tool takes two calls:

1. Call `top_up_wallet` with an `amount`, like `"25.00"`. It returns `payment_required` and the challenge.
2. Pay the challenge, then call `top_up_wallet` again with the same amount and either:
   * `payment_credential`: the credential from your MPP wallet, or
   * `spt` plus `challenge`: a Stripe Shared Payment Token issued for the challenge, and the challenge itself.

MCP clients that support MPP's payment binding pay the challenge automatically from the tool result.

The result's `status` is `settled`, `pending` (paid, credit landing, don't pay again), or `unconfirmed` (don't pay again on your own).

<Info>
  `top_up_wallet` is available on the main MCP server. The ChatGPT and Claude directory apps don't include it.
</Info>

***

## Never Paying Twice

TinyFish is built so one top-up is charged once:

* **A replayed payment is never charged again.** Sending the same credential twice credits the wallet once.
* **A failed paid retry never gets a new challenge.** Some failures can happen after a charge, for example a timeout while Stripe is processing. So TinyFish answers `402` without a challenge, and an MPP wallet has nothing to pay automatically.
* **A charge that went through is credited automatically,** even if something fails right after it.

If your agent gets a `402` without a challenge, a `202`, or a request that errors or times out after it sent a payment, it shouldn't start a new top-up on its own. If the balance hasn't increased after 10 minutes, it should ask you first.

<Warning>
  A declined card also comes back as a `402` without a challenge, and charges nothing. To try again, start a new top-up with a different payment method.
</Warning>

***

## Refunds

For a refund of an agent top-up, contact support with the `payment_reference` from the response.

## Learn More

* [Machine Payments Protocol](https://mpp.dev/overview)
* [Stripe machine payments](https://docs.stripe.com/payments/machine)
* [Link agent wallet](https://docs.stripe.com/agentic-commerce/link-agent-wallet)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.