Skip to main content
Glama

invoice_pay

Build the plan to pay an invoice from payer, with the token payer holds (default: the invoice token). Nothing is signed or sent here. Both wallets are screened first (payer_blocked, receiver_blocked); when the invoice has checks ["scorechain"] (see invoice_get), the creator chose and paid the Scorechain sanctions API, so this call sends the payer wallet and the receiver wallet to Scorechain, a third party (an invoice created before 22/10/2026 with the then-free Scorechain keeps running it without a charge). method "transfer": same token, a direct transfer built from the stored invoice (no fee, no gain; the receiver sees the payer as sender). method "swap": another token; amountIn is computed so the GUARANTEED minimum output covers the requested amount, the route is always the one with GAIN when there is one, and the output goes straight to the receiver (the transaction is public and signed by the payer, so the receiver can see the paying wallet on-chain). Any surplus over the requested amount goes to the receiver. plan has the same shape as a swap_build plan: on EVM sign steps[] in order with prepare_signing (approve steps first, then the transaction); on Solana pass {transaction, executionRef} to prepare_signing and POST the signed transaction to /v1/svm/execute. If simulation.status is approval_required, send the approve and call invoice_pay again. When the invoice has paid checks, the creator must have paid the analysis first (analysis_unpaid, 409). With "merkle-science" this call then sends the payer wallet and the receiver wallet to Didit/Merkle Science, and a HIGH or CRITICAL risk (score 70 or more) refuses with payer_blocked or receiver_blocked; the detail shows in invoice_get analysis.report. At most 3 different payer wallets are analysed per invoice by each paid check; a 4th gets analysis_attempts_exceeded (429). Since 23/10/2026 the payer proves the wallet BEFORE the paid analysis runs on it: over MCP that proof is the destination authorization signed by the payer for this invoice's receiver (destination_challenge with wallet = payer, receiver = the invoice receiver, chainId of the invoice, sign the message, then destination_authorize). Without it this call returns payer_signature_required (401) and no analysis slot is spent. Invoices with payerChecks on Solana or enabled EVM networks (see invoice_get payerChecks and split): the paid analysis the receiver chose runs HERE, on the payer wallet, after its free screening passes; it is always on and cannot be switched off. The payer proves the wallet first (destination_challenge/destination_authorize; payer_signature_required 401). At most 2 different payer wallets per invoice (analysis_attempts_exceeded 429); analysis_offer_suspended (403) when the receiving wallet left 2 approved paid analyses without payment. Approved, method "transfer" is ONE payment transaction with the split (on EVM, sign the exact approve step first, then VurtoInvoiceSplit.pay): split.receiverAmount to the receiver and split.fee to the Vurto fee wallet; only that transaction settles the invoice. With another token, method "swap_then_transfer": plan is a swap into the PAYER's own wallet (never straight to the receiver); once it confirms, call invoice_pay again with next.body (tokenIn = the invoice token) and sign the split. If the payer contracted the receiver analysis (invoice_analysis_pay), it must be paid first (receiver_analysis_unpaid 409) and a rejected receiver gets receiver_blocked. Then call invoice_report_payment with the hash (EVM) or signature (Solana). Errors: price_moved (the minimum fell below the request between quote and build — call again), no_route, native_sol_only (an invoice in SOL can only be paid in SOL), invoice_already_paid, private_invoice_paused (a private invoice created before 14/10/2026, paused until the Vurto vault exists). Both wallets are screened before the plan is built: the paying one (payer_blocked) and the receiving one (receiver_blocked). screening_unavailable (503) means the screening could not finish, try again in a few seconds.

Input Schema

NameRequiredDescriptionDefault
idYesINV-XXXX-XXXX or the 8-character id.
payerYesThe wallet that will sign and pay, on the invoice network.
tokenInNoOptional: address/mint or symbol of the token the payer pays with. Omit to pay in the invoice token.
slippageBpsNoOptional, default 50. The guaranteed minimum is computed after it, so a tighter slippage asks the payer for less.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With only generic annotations, the description carries extensive behavioral context: it discloses third-party Scorechain/Didit screening, auth requirements via destination_challenge/destination_authorize, rate limits like 3 or 2 payer wallets per invoice, status codes such as payer_signature_required and analysis_attempts_exceeded, and the fact that nothing is signed or sent here.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence is front-loaded well, but the rest is a dense run-on wall of text. Key points are repeated, such as the both-wallet screening and the payer-proof-before-analysis flow, making it harder than necessary to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex payment-planning tool with no output schema, the description is unusually complete: it explains the returned plan shape, EVM and Solana signing flows, required follow-up calls, screening behavior, paid analysis constraints, and the major error conditions an agent will encounter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description still adds meaningful context beyond the schema by explaining that tokenIn defaults to the invoice token and that choosing another token changes the method, and by connecting slippageBps to the guaranteed minimum and the payer's requested amount.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening states a specific verb and resource: 'Build the plan to pay an invoice from payer,' and immediately clarifies that nothing is signed or sent. It distinguishes the transfer and swap variants and their scope, so an agent can tell what the tool does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit branching instructions: use method "transfer" for same-token payment, "swap" for another token, and "swap_then_transfer" for the split flow. It also names required follow-ups like prepare_signing, invoice_report_payment, destination_authorize, and invoice_pay again with next.body, plus error-specific alternatives such as retrying after price_moved.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources