---
title: "Top up wallet (agent-paid)"
method: POST
path: "/v1/wallet/top-up"
tags: ["Wallet"]
---

# Top up wallet (agent-paid)

`POST /v1/wallet/top-up`

## Request

- Base URL: `https://agent.tinyfish.ai`
- URL: `https://agent.tinyfish.ai/v1/wallet/top-up`
- Auth: API key in header `X-API-Key`

Add money to the wallet, paid by the calling agent over the Machine Payments Protocol (MPP). The first call answers 402 with a payment challenge in WWW-Authenticate; retry with a Payment-Authorization credential to settle the charge and credit the wallet.

## Request body

- object: A wallet top-up an agent pays for with the Machine Payments Protocol.
  - `amount` string, required: Amount to add in USD, from 10.00 to 500.00. Charged over MPP once the agent presents a payment credential.

## Response `200`

Payment settled and wallet credited

- object: The settled top-up and the balance it produced.
  - `status` 'settled' | 'pending', required: settled: the wallet is credited. pending (HTTP 202): the card was charged and the credit lands shortly via webhook; do not pay again.
  - `amount` string, required
  - `currency` 'USD', required
  - `payment_reference` string, required: Stripe PaymentIntent that settled this top-up.
  - `ledger_entry_id` string, nullable, required
  - `available_balance` string, nullable, required: Spendable balance after the credit landed; null when pending or unreadable.
  - `hint` string: On a 202: do not pay again.

## Other responses

- `202`: Payment settled; the wallet credit is pending and lands via webhook. Do not pay again.
- `400`: Invalid amount (error code INVALID_INPUT)
- `401`: Unauthorized - Invalid or missing API key
- `402`: Payment required. Either an MPP challenge in the WWW-Authenticate header (pay it and retry), or, after a payment that was not accepted, a problem body with no challenge and a hint (do not pay again on your own).
- `403`: Forbidden - Wallet isn't available for organizations yet.
- `404`: Agent-paid top-ups are not enabled on this deployment, or the account is not on wallet billing (error code FEATURE_NOT_AVAILABLE).
- `500`: Internal server error
- `503`: Organization could not be resolved (organization_unresolved). Retry later.

---

[API](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2.md) · [All operations](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/revisions/c48ef855099d?raw)