> ## 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. # Top up wallet (agent-paid) > 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. ## OpenAPI ````yaml https://agent.tinyfish.ai/v1/openapi/main post /v1/wallet/top-up openapi: 3.0.0 info: title: TinyFish Web Agent Automation API version: 1.0.0 description: >- REST API for running AI-powered browser automations. Execute tasks on any website using natural language instructions. contact: name: TinyFish Support email: support@tinyfish.ai servers: - url: https://agent.tinyfish.ai description: Production security: [] tags: - name: Automation description: Browser automation endpoints for executing tasks on websites - name: Runs description: Endpoints for retrieving automation run data - name: Browser description: Remote browser session endpoints - name: Fetch description: Fetch URLs and extract clean page content - name: Search description: Web search endpoints - name: Browser Context Profiles description: >- Saved browser context endpoints for managing reusable login state, cookies, storage, and profile setup sessions - name: Vault description: >- Vault credential management endpoints for connecting password managers and managing stored credentials - name: Research description: Source-backed research report endpoints - name: Wallet description: Wallet balance, auto-reload, rates, and top-up endpoints paths: /v1/wallet/top-up: post: tags: - Wallet summary: Top up wallet (agent-paid) description: >- 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. operationId: topUpWallet requestBody: required: true content: application/json: schema: type: object properties: amount: type: string pattern: ^(?=.*[1-9])(?:0|[1-9]\d{0,11})(?:\.\d{1,2})?$ description: >- Amount to add in USD, from 10.00 to 500.00. Charged over MPP once the agent presents a payment credential. example: '25.00' required: - amount description: >- A wallet top-up an agent pays for with the Machine Payments Protocol. responses: '200': description: Payment settled and wallet credited content: application/json: schema: type: object properties: status: type: string enum: - settled - pending description: >- settled: the wallet is credited. pending (HTTP 202): the card was charged and the credit lands shortly via webhook; do not pay again. amount: type: string pattern: ^(?=.*[1-9])(?:0|[1-9]\d{0,11})(?:\.\d{1,6})?$ example: '25.00' currency: type: string enum: - USD example: USD payment_reference: type: string description: Stripe PaymentIntent that settled this top-up. example: pi_3QxYz2Ab ledger_entry_id: type: string nullable: true example: wallet-grant:machine-payment:pi_3QxYz2Ab available_balance: type: string nullable: true pattern: ^-?(?:0|[1-9]\d{0,11})(?:\.\d{1,6})?$ description: >- Spendable balance after the credit landed; null when pending or unreadable. example: '31.44' hint: type: string description: 'On a 202: do not pay again.' required: - status - amount - currency - payment_reference - ledger_entry_id - available_balance description: The settled top-up and the balance it produced. '202': description: >- Payment settled; the wallet credit is pending and lands via webhook. Do not pay again. content: application/json: schema: type: object properties: status: type: string enum: - settled - pending description: >- settled: the wallet is credited. pending (HTTP 202): the card was charged and the credit lands shortly via webhook; do not pay again. amount: type: string pattern: ^(?=.*[1-9])(?:0|[1-9]\d{0,11})(?:\.\d{1,6})?$ example: '25.00' currency: type: string enum: - USD example: USD payment_reference: type: string description: Stripe PaymentIntent that settled this top-up. example: pi_3QxYz2Ab ledger_entry_id: type: string nullable: true example: wallet-grant:machine-payment:pi_3QxYz2Ab available_balance: type: string nullable: true pattern: ^-?(?:0|[1-9]\d{0,11})(?:\.\d{1,6})?$ description: >- Spendable balance after the credit landed; null when pending or unreadable. example: '31.44' hint: type: string description: 'On a 202: do not pay again.' required: - status - amount - currency - payment_reference - ledger_entry_id - available_balance description: The settled top-up and the balance it produced. '400': description: Invalid amount (error code INVALID_INPUT) content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - VAULT_RECONNECT_REQUIRED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - VAULT_RECONNECT_REQUIRED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '402': description: >- 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). content: application/problem+json: schema: type: object properties: type: type: string description: MPP problem type, on a challenge. title: type: string status: type: number enum: - 402 detail: type: string challengeId: type: string hint: type: string description: >- On a paid retry that was not accepted: do not pay again on your own. required: - status description: >- Without a payment: an MPP challenge to pay and retry. With one that was not accepted: no new challenge, and a hint. '404': description: >- Agent-paid top-ups are not enabled on this deployment, or the account is not on wallet billing (error code FEATURE_NOT_AVAILABLE). content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - VAULT_RECONNECT_REQUIRED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '500': description: Internal server error content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - VAULT_RECONNECT_REQUIRED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication. Get your key from the API Keys page. ````