---
title: "Buy credits as an agent (machine payment)"
method: POST
path: "/v1/billing/machine-topup"
---

# Buy credits as an agent (machine payment)

`POST /v1/billing/machine-topup`

## Request

- Base URL: `https://api.toolrouter.com`
- URL: `https://api.toolrouter.com/v1/billing/machine-topup`
- Auth: one of:
  - HTTP bearer
  - none

Answers with a payment challenge in the WWW-Authenticate header. Pay it and retry the same request. With an API key, the credits go to that key's account. Without one, a new account is created when the payment settles and its API key is returned in the response. An empty body asks for the $1 minimum.

## Request body

- object
  - `amount_usd` number: Credit value to buy, in US dollars, no finer than whole cents. Defaults to the $1 minimum.

## Response `200`

Payment accepted and credits added

- MachineTopUpResult: Returned once the payment settles and the credits are added.
  - `credited_usd` number, required: Credit value added to the account.
  - `charged_usd` number, required: Amount actually paid, including the purchase fee.
  - `balance_usd` number, required: Credit balance after the top-up.
  - `payment_ref` string, required: Settled payment reference the grant is keyed on.
  - `api_key` string: Only when paid without an API key: the new account's API key. Shown once.
  - `account_id` string: Only when paid without an API key: the new account id.
  - `claim_url` string: Only when paid without an API key: link for the user to claim and manage the account.
  - `message` string: Only when paid without an API key: how to use the new key.

## Other responses

- `400`: Machine-readable ToolRouter error
- `401`: Machine-readable ToolRouter error
- `402`: Payment required — the challenge is in the WWW-Authenticate header
- `default`: Machine-readable ToolRouter error

---

[API](https://skmtc.dev/toolrouter/apis/toolrouter-api.md) · [All operations](https://skmtc.dev/toolrouter/apis/toolrouter-api/llms.txt) · [OpenAPI document](https://skmtc.dev/toolrouter/apis/toolrouter-api/revisions/b21ed1d64e24?raw)