---
title: "Call Tool"
method: POST
path: "/tools/{tool_name}/call"
---

# Call Tool

`POST /tools/{tool_name}/call`

## Request

- Base URL: `https://agentpay.tools` (the document declares no server; this is the origin it was published from)
- URL: `https://agentpay.tools/tools/{tool_name}/call`
- Auth: none required

Main endpoint — call a paid MCP tool.

Supports two payment paths:
  Stellar — X-Payment: tx_hash=<hash>,from=<addr>,id=<payment_id>
  Base    — PAYMENT-SIGNATURE: <base64(PaymentPayload JSON)>

Flow:
  1. Neither header → _issue_402 (advertise both options) — the body is
     parsed leniently first: a bare/malformed POST still gets the 402,
     never a 422.
  2. X-Payment → _settle_stellar, then _execute_and_log
  3. PAYMENT-SIGNATURE + $0 tool → _settle_free_v2 (no on-chain settle)
  4. PAYMENT-SIGNATURE → _settle_base_path, then _execute_and_log
  (2–4 validate the body strictly before settling, so a malformed paid
  call 422s without burning the payment.)

## Path parameters

- `tool_name` string, required

## Headers

- `x-payment` string, nullable
- `x-agent-address` string, nullable
- `payment-signature` string, nullable

## Request body

- object: Body of POST /tools/{name}/call. Canonical shape nests tool arguments under "parameters", but some clients send them at the top level ({"symbol": "SOL"} instead of {"parameters": {"symbol": "SOL"}}). Pydantic used to silently discard unknown keys, so those calls ran on tool defaults with no error. The validator below folds unrecognized top-level keys into `parameters` whenever `parameters` itself is empty, so both shapes work; nested callers are byte-for-byte unaffected.
  - `parameters` object
  - `agent_address` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

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