MCP tool inputs and outputs

Spendkit exposes seven tools to an authenticated Agent connection. Each call is an MCP tools/call request: set params.name to the tool name and params.arguments to the input object below. To start with working code, copy a language example; to inspect the transport, see the HTTP request envelope.

Conventions for every tool

• amount is a positive decimal string, such as "0.01", never a JSON number. Atomic token amounts are returned separately as strings.
• recipient is a nonzero 0x-prefixed EVM address. Optional token is a symbol such as "USDG", not a contract address. Omit it to use the Agent default.
• Examples show selected fields with placeholder IDs and addresses. Every tool result also includes structuredContent.spendkit.traceId, and may include spendkit.nextAction or spendkit.recovery.
• Read result.structuredContent or parse its text content. A Policy refusal normally has result.isError: true and structuredContent.allowed: false, even when HTTP status is 200. Invalid JSON-RPC requests instead return a top-level error.

spendkit_get_connection

Input: {}. Output: connection (Client ID and scopes), agent (Agent ID, bound wallet, readiness), network (network key, chain ID, RPC URL, Router address), authentication (token expiry), and paymentModel (which component sends transactions).

Input: {}
Selected output: {
  "connection": { "clientId": "<client-id>", "scopes": ["policy:read", "payment:preview"] },
  "agent": { "id": "<agent-id>", "paymentWallet": { "address": "0x..." }, "paymentReady": true },
  "network": { "key": "arbitrum-sepolia", "chainId": 421614, "rpcUrl": "https://...", "routerAddress": "0x..." },
  "paymentModel": { "serverBroadcastsPayment": false, "paymentWalletSubmitsTransaction": true }
}

Match agent.paymentWallet.address to the address controlled by your wallet signer. Authentication can succeed while paymentReady is false.

spendkit_get_policy

Input: {}. Output when ready: ready: true, Policy ID, owner and Agent identifiers, token, limits, daily spending, remaining daily amount, allowlist state, enabled/paused/revoked state, and _raw atomic amounts. Decimal limits are strings. Without a linked wallet, Policy, or ready Router, the output has ready: false and a reason.

Input: {}
Selected output: {
  "ready": true, "policyId": 42, "token": "USDG", "decimals": 6,
  "perTransactionLimit": "1", "dailyLimit": "10",
  "spentToday": "0.25", "remainingDaily": "9.75",
  "enabled": true, "emergencyPaused": false, "revoked": false,
  "recipientAllowlistEnabled": false
}

spendkit_preview_payment

Output: allowed and reason. On ALLOW, also amount, amountAtomic, recipient, token, network, owner, policy, and wallet. On DENY, reason explains why; Policy or wallet detail may be present. Preview does not create an authorization or send funds.

Input: { "amount": "0.01", "recipient": "0x1111111111111111111111111111111111111111", "token": "USDG" }
Selected ALLOW output: { "allowed": true, "reason": "policy_allows_payment", "amount": "0.01", "amountAtomic": "10000", "token": "USDG" }
Selected DENY output: { "allowed": false, "reason": "per_transaction_limit_exceeded" }

spendkit_authorize_payment

Output on ALLOW: intentId, status: "authorized", duplicate, authorization (authorization ID, Policy ID, Agent ID, Payment Wallet, token address, recipient, atomic amount, deadline), signature, and transaction (chainId, from, to, data, value). This response is permission to submit one specific Router transaction; it is not a completed payment.

Input: { "amount": "0.01", "recipient": "0x1111111111111111111111111111111111111111", "token": "USDG", "idempotencyKey": "order-123" }
Selected ALLOW output: {
  "allowed": true, "duplicate": false, "intentId": "<intent-id>", "status": "authorized",
  "authorization": { "paymentWallet": "0x...", "recipient": "0x...", "token": "0x...", "amount": "10000", "deadline": "..." },
  "signature": "0x...",
  "transaction": { "chainId": 421614, "from": "0x...", "to": "0x...", "data": "0x...", "value": "0x0" }
}
Selected DENY output: { "allowed": false, "reason": "policy_daily_limit_exceeded", "intentId": "<intent-id-or-null>" }

A repeated key may return duplicate: true and an existing intent state instead of a new transaction. Reusing it with changed details returns idempotency_key_conflict. Inspect the existing intent before any retry. Compare the authorized amount, recipient, wallet, chain, and Router with the intended payment before sending the exact returned transaction.

spendkit_record_payment

Input: intentId (required nonempty string) and txHash (required 32-byte 0x hash from the bound wallet's submitted transaction). Output: accepted, intentId, current status, and txHash. A rejected result has accepted: false and error. This call can reconcile a receipt immediately; it does not send a transaction.

Keep this call in the payment path: it links the transaction your wallet sent to its Spendkit intent for prompt tracking and Payment Activity updates. Without it, status may remain outdated until onchain reconciliation finds the transaction. The onchain Router still enforces spending limits. If this call fails after wallet submission, retry with the same intentId and txHash or check status; never submit a second transaction just to retry recording.

Input: { "intentId": "<intent-id>", "txHash": "0x<64-hex-characters>" }
Selected output: { "accepted": true, "intentId": "<intent-id>", "status": "submitted", "txHash": "0x..." }

spendkit_get_payment_status

Input: intentId (required nonempty string). Output: intentId, lower-case status, txHash or null, failureCode, failureMessage, recipient, atomic amount, token symbol, Policy ID, and timestamps. A missing or inaccessible intent returns {"status":"not_found"}. Querying status can trigger reconciliation.

Input: { "intentId": "<intent-id>" }
Selected output: { "intentId": "<intent-id>", "status": "confirmed", "txHash": "0x...", "failureCode": null, "amountAtomic": "10000", "token": "USDG" }

Lifecycle values include authorized, signing, submitted, confirmed, rejected, expired, reverted, and failed. Treat confirmed as successful payment; authorized and submitted are not final success.

spendkit_list_payments

Input: {} for the default 50 results, or {"limit":20} with an integer from 1 to 100. Output: rows for this authenticated Agent. Each row contains intentId, status, policyId, token, amountAtomic, recipient, txHash, failureCode, failureMessage, reconciliationState, createdAt, and updatedAt.

Input: { "limit": 20 }
Selected output: { "rows": [{ "intentId": "<intent-id>", "status": "confirmed", "token": "USDG", "amountAtomic": "10000", "txHash": "0x...", "reconciliationState": "settled" }] }