Agent Payments

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), 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.

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.

How It Works

Your agent asks TinyFish to top up, say $25.
TinyFish answers with an HTTP 402 payment challenge: the amount, the currency, and who to pay.
Your agent’s wallet issues a one-time Shared Payment Token (SPT) for that amount. Your card details never reach the agent or TinyFish.
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.

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.

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.

Ask for a top-up

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"

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.

Retry with the payment

Send the same request again, with the same amount, plus the credential:

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"}'

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 instead.

A successful top-up looks like this:

{
  "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), 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:

Call top_up_wallet with an amount, like "25.00". It returns payment_required and the challenge.
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).

top_up_wallet is available on the main MCP server. The ChatGPT and Claude directory apps don’t include it.

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.

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.

Refunds

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

Start Here

Agent API

Search API

Monitor

Fetch API

Browser API

Research API (Beta)

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

How It Works

REST API

Responses

MCP

Never Paying Twice

Refunds

Learn More

​How It Works

​REST API

​Responses

​MCP

​Never Paying Twice

​Refunds

​Learn More

How It Works

REST API

Responses

MCP

Never Paying Twice

Refunds

Learn More