Skip to content

Tools ​

Every result is a JSON object with an environment field (test or live). It is returned both as text and as structuredContent. API responses are parsed through the matching @klappay/types schema first: fields the schema doesn't know are dropped, and a response that doesn't match at all becomes an unexpected_response error instead of being passed through.

Ids are checked before any request is sent: charge ids look like ch_..., webhook ids wh_..., delivery ids ev_..., recipient ids rc_..., followed by letters and digits only.

Errors ​

A failed call returns isError: true with:

json
{
  "environment": "test",
  "error": { "code": "charge_not_found", "status": 404, "message": "Charge not found" }
}

code and status come straight from the Klap API. Locally detected problems use validation_error (invalid input), unexpected_response (the API answered with something the schema rejects) or unexpected_error (anything else; details go to the server's stderr only). Input that fails the tool's schema is rejected by the MCP SDK before the tool runs.

Read tools ​

Available in every environment, annotated readOnlyHint: true.

klap_status ​

No input. Returns { environment, host }, where host is the API host (and port) only. Makes no API call.

charges_get ​

Input
idcharge id
includeMetadataboolean, default false

Returns { charge } (ChargeSchema). The charge's metadata object (free-form merchant data, which may contain customer details) is left out unless includeMetadata is true.

amount is what the payer sends and already includes gasFeeAmount, the network gas fee the payer covers, so it can be higher than the amount asked for. requestedAmount is the amount asked for at creation (null on older charges), and amount always equals merchantAmount + feeAmount + gasFeeAmount. A transfer below the payment minimum (0.10 live, 0.01 test) doesn't count toward amountReceived unless it completes the charge.

When settlementStatus is below_minimum, the funds haven't covered the gas to pay out, so Klap sent nothing. The charge then carries selfSettlement: the split address, its recipients and shares, the distributor fee, the salt and the affected (network, token) pairs. This server doesn't settle anything on-chain; these are the terms someone would use to do it themselves.

charges_list ​

Input
statusoptional ChargeStatusSchema value
token / networkoptional, filter on the pair actually paid (paidWith), not the accepted ones
sinceoptional ISO 8601 timestamp, filters on createdAt
isOverpaidoptional "true" or "false"
limit1–100, default 20
cursorthe previous page's nextCursor
includeMetadataboolean, default false

Input is ListChargesSchema without environment: the server always sends its own, so a list can never return the other environment's charges, and passing environment is rejected. Returns { data, nextCursor, hasMore } (PaginatedChargesSchema), newest first, with each charge's metadata left out unless includeMetadata is true.

charges_timeline ​

Input { id }. Returns { chargeId, events } (TimelineEventSchema[]).

charges_prepare_release / charges_prepare_refund ​

Input { id } of an escrow charge. Returns { chargeId, transaction } (EscrowSafeTransactionSchema): the exact Safe transaction the release or refund would execute, with destination, token, amount in base units, chain id, Safe nonce, safeTxHash and the EIP-712 typedData the escrow's releaser signs. It is only valid while the escrow's balance is unchanged.

These are read-only: nothing is signed or submitted, and release/ refund themselves are not available through this server (see Security). The API key needs the charges:write scope even though the call changes nothing. API errors such as 422 escrow_safe_mismatch come back as a normal error result.

recipients_list ​

Input
limit1–100, default 20
cursorthe previous page's nextCursor
includeLabelsboolean, default false

Returns { data, nextCursor, hasMore } (PaginatedRecipientsSchema) with this environment's non-revoked recipients, newest first. Each label (free-form merchant text, which may name a person) is left out unless includeLabels is true. The API key needs the recipients:read scope. Registering, changing or revoking a recipient is not available through this server (see Security).

recipients_transferability ​

Input { id } of a recipient. Returns { recipientId, address, pairs } (RecipientTransferabilitySchema). For each token/network pair enabled in this environment, receive says whether the address can be credited and send whether it can move funds out. Each is allowed, restricted or unknown, read from the token issuer's own contract. pairs is empty for a TRON address.

Use it to explain a 422 recipient_transfer_restricted from charges_create, which only happens when receive is restricted. The API key needs the recipients:read scope.

webhooks_list ​

No input. Returns { webhooks } (WebhookListItemSchema[]). Each url is reduced to origin + path: any username/password, query string and fragment are removed. Secrets are never returned, only the display hint.

webhooks_list_deliveries ​

Input
webhookIdwebhook id
limit1–100, default 20
cursorthe previous page's nextCursor

Returns { webhookId, data, nextCursor, hasMore } (PaginatedWebhookDeliveriesSchema).

networks_get ​

No input. Returns { acceptedPayments } (CapabilitiesSchema): the (token, network) pairs this environment accepts for new charges.

metrics_query ​

Input { query }, where query is a MetricsQuerySchema request (resource, metrics, dateRange, optional filters/groupBy/limit) without environment: the server always fills in its own environment, so a query can never ask for the other environment's data. Returns the MetricsQueryResultSchema fields (data rows and meta).

Write tools ​

Available in test, and in live only with KLAP_MCP_ALLOW_LIVE_WRITES=1. Annotated readOnlyHint: false.

charges_create ​

Input is CreateChargeSchema without escrow and redirectUrl; sending either is rejected. Pass idempotencyKey to make a retry safe; without it every call creates a new charge. Returns { charge } without metadata (including amount, acceptedPayments and splitRecipients). The returned amount includes gasFeeAmount, so show that to the payer rather than the amount you passed.

A charge that accepts ethereum can't accept any other network; mixing them is rejected before any request is sent. API errors such as 422 amount_below_minimum (below 0.10 live, 5.00 live on ethereum, 0.01 test), 422 recipient_transfer_restricted and 503 gas_quote_unavailable come back as a normal error result.

Annotations: destructiveHint: false, idempotentHint: false.

charges_check ​

Input
idcharge id
txHashoptional 0x + 64 hex transaction hash
networkrequired together with txHash

Asks the API to re-check the charge on-chain now. Returns { charge } (CheckChargeResponseSchema without metadata).

When txHash actually paid the charge, the result carries on-chain evidence of who paid: transactionSender (the transaction's own from), tokenSenders (the from of each paying accepted-token transfer, which covers a wallet behind a gas-sponsoring relayer) and userOperationSenders (the ERC-4337 account whose own user operation paid). This is evidence, not identity. Both arrays are [] whenever transactionSender is null.

Annotations: destructiveHint: false, idempotentHint: true.

webhooks_retry_delivery ​

Input { webhookId, deliveryId }. Re-sends one delivery to its endpoint; the receiver processes that event again. Returns { webhookId, deliveryId, retried: true }.

Annotations: destructiveHint: true.

Sandbox tool ​

sandbox_trigger ​

Test environment only, never registered in live.

Input
chargeIdcharge id
eventcharge.confirmed, charge.partially_paid, charge.overpaid, charge.expired, charge.underpaid, charge.settled, charge.settlement_failed or charge.settlement_below_minimum
amountoptional, for charge.partially_paid/charge.overpaid

Returns { charge } without metadata. Annotations: destructiveHint: true (the state change can't be undone on that charge).

Docs live in ./docs — the source of truth for both the package and this site.