> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools Reference

> Reference for Conto MCP tools

<Info>
  All MCP server API requests have a **30-second timeout** and all user-supplied parameters are
  sanitized before URL interpolation to prevent path injection.
</Info>

## Payments (6)

| Tool                       | Description                                                  |
| -------------------------- | ------------------------------------------------------------ |
| `pay`                      | Request and execute a payment in one step                    |
| `request_payment`          | Request payment authorization (check policies first)         |
| `execute_payment`          | Execute a previously approved payment                        |
| `check_payment_status`     | Check status of a payment request                            |
| `approve_external_payment` | Request approval for an external (agent-held) wallet payment |
| `confirm_external_payment` | Confirm an externally-executed payment with tx hash          |

### pay

Request and execute a payment in one step. Combines `request_payment` + `execute_payment`. Fails if the payment is denied or requires manual approval.

**Parameters:**

| Parameter          | Type   | Required | Description                   |
| ------------------ | ------ | -------- | ----------------------------- |
| `amount`           | number | Yes      | Amount in USDC                |
| `recipientAddress` | string | Yes      | Recipient wallet address      |
| `recipientName`    | string | No       | Human-readable recipient name |
| `purpose`          | string | No       | Why this payment is needed    |
| `category`         | string | No       | Spend category for analytics  |
| `sessionId`        | string | No       | Session/correlation ID        |

### request\_payment

Request authorization for a payment. Evaluates spending policies and returns whether the payment is approved, denied, or requires manual approval.

**Parameters:** Same as `pay`.

**Returns:** `requestId`, `status` (`APPROVED` / `DENIED` / `REQUIRES_APPROVAL`), `wallet`, `reasons`, and `violations`.

### execute\_payment

Execute a previously approved payment request.

| Parameter   | Type   | Required | Description                          |
| ----------- | ------ | -------- | ------------------------------------ |
| `requestId` | string | Yes      | The requestId from `request_payment` |

### approve\_external\_payment

Request approval for a payment from an external (agent-held) wallet.

| Parameter          | Type   | Required | Description                                             |
| ------------------ | ------ | -------- | ------------------------------------------------------- |
| `amount`           | number | Yes      | Amount in USDC                                          |
| `recipientAddress` | string | Yes      | Recipient wallet address                                |
| `senderAddress`    | string | Yes      | Sender wallet address (agent-held)                      |
| `recipientName`    | string | No       | Recipient name                                          |
| `purpose`          | string | No       | Payment purpose                                         |
| `category`         | string | No       | Spend category                                          |
| `context`          | object | No       | Additional context metadata                             |
| `chainId`          | string | Yes      | Chain ID as a string (e.g. `"42431"` for Tempo Testnet) |

### confirm\_external\_payment

Confirm an externally-executed payment was completed onchain.

| Parameter       | Type   | Required | Description                                    |
| --------------- | ------ | -------- | ---------------------------------------------- |
| `requestId`     | string | Yes      | Payment request ID from approval               |
| `txHash`        | string | Yes      | Onchain transaction hash                       |
| `approvalToken` | string | Yes      | Approval token from `approve_external_payment` |

***

## Wallets & Limits (3)

| Tool                  | Description                                        |
| --------------------- | -------------------------------------------------- |
| `get_wallets`         | List all wallets linked to this agent              |
| `get_wallet`          | Get details of a specific wallet                   |
| `get_spending_limits` | Get current spending limits and remaining balances |

### get\_wallet

| Parameter  | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `walletId` | string | Yes      | Wallet ID   |

***

## Budget Requests (2)

| Tool                 | Description                                       |
| -------------------- | ------------------------------------------------- |
| `request_budget`     | Request a spending budget for human approval      |
| `get_budget_request` | Check budget request status and remaining balance |

### request\_budget

Request a spending budget for payments. Submits a request for human approval. Only one active budget request per agent at a time. Applies to all payment types (standard, x402, MPP).

| Parameter  | Type   | Required | Description                                          |
| ---------- | ------ | -------- | ---------------------------------------------------- |
| `amount`   | number | Yes      | Requested budget in USDC                             |
| `purpose`  | string | Yes      | What this budget is for (shown to reviewer)          |
| `category` | string | No       | Spend category (e.g., API\_PROVIDER, INFRASTRUCTURE) |
| `metadata` | object | No       | Additional context                                   |

### get\_budget\_request

Check status and remaining balance of your budget requests. Use to poll for approval after submitting a request, and to monitor remaining budget during spending.

| Parameter         | Type   | Required | Description                                             |
| ----------------- | ------ | -------- | ------------------------------------------------------- |
| `budgetRequestId` | string | No       | Specific budget request ID                              |
| `status`          | string | No       | Filter: PENDING, APPROVED, REJECTED, EXPIRED, EXHAUSTED |

***

## Transactions (3)

| Tool                | Description                             |
| ------------------- | --------------------------------------- |
| `list_transactions` | List transactions with optional filters |
| `get_transaction`   | Get details of a specific transaction   |
| `retry_transaction` | Retry a failed transaction              |

### list\_transactions

| Parameter | Type   | Required | Description                        |
| --------- | ------ | -------- | ---------------------------------- |
| `status`  | string | No       | Filter: PENDING, CONFIRMED, FAILED |
| `from`    | string | No       | Start date (ISO string)            |
| `to`      | string | No       | End date (ISO string)              |
| `limit`   | number | No       | Results per page (max 100)         |
| `offset`  | number | No       | Pagination offset                  |

***

## x402 Protocol (4)

| Tool                 | Description                                        |
| -------------------- | -------------------------------------------------- |
| `x402_get_budget`    | Check remaining x402 budget and burn rate          |
| `x402_pre_authorize` | Pre-authorize an x402 API payment against policies |
| `x402_record`        | Record a completed x402 payment (single or batch)  |
| `x402_list_services` | List x402 services with spend and pricing stats    |

### x402\_pre\_authorize

| Parameter          | Type   | Required | Description                   |
| ------------------ | ------ | -------- | ----------------------------- |
| `amount`           | number | Yes      | Payment amount                |
| `recipientAddress` | string | Yes      | Facilitator/recipient address |
| `resourceUrl`      | string | Yes      | URL of the API endpoint       |
| `facilitator`      | string | No       | x402 facilitator address      |
| `walletId`         | string | No       | Preferred wallet ID           |
| `sessionId`        | string | No       | Session ID for grouping calls |
| `category`         | string | No       | Spend category                |

`serviceDomain` is derived automatically from `resourceUrl`.

### x402\_record

| Parameter          | Type   | Required | Description                                |
| ------------------ | ------ | -------- | ------------------------------------------ |
| `amount`           | number | Yes      | Payment amount                             |
| `recipientAddress` | string | Yes      | Recipient address                          |
| `resourceUrl`      | string | Yes      | API endpoint URL                           |
| `txHash`           | string | No       | Onchain transaction hash                   |
| `batchItems`       | array  | No       | Array of micropayments for batch recording |

### x402\_list\_services

| Parameter | Type   | Required | Description                                            |
| --------- | ------ | -------- | ------------------------------------------------------ |
| `period`  | string | No       | Time period: '24h', '7d', '30d', '90d' (default: '7d') |
| `limit`   | number | No       | Max results (default: 50)                              |

***

## MPP Protocol (4)

| Tool                | Description                                      |
| ------------------- | ------------------------------------------------ |
| `mpp_get_budget`    | Check remaining MPP budget and burn rate         |
| `mpp_pre_authorize` | Pre-authorize an MPP payment against policies    |
| `mpp_record`        | Record a completed MPP payment (single or batch) |
| `mpp_list_services` | List MPP services with spend and pricing stats   |

### mpp\_pre\_authorize

| Parameter          | Type   | Required | Description                |
| ------------------ | ------ | -------- | -------------------------- |
| `amount`           | number | Yes      | Payment amount             |
| `recipientAddress` | string | Yes      | Recipient address          |
| `resourceUrl`      | string | Yes      | API endpoint URL           |
| `walletId`         | string | No       | Preferred wallet ID        |
| `intent`           | string | No       | 'charge' or 'session'      |
| `sessionId`        | string | No       | Session ID                 |
| `paymentMethod`    | string | No       | Payment method             |
| `depositAmount`    | number | No       | Deposit for session intent |
| `category`         | string | No       | Spend category             |

### mpp\_record

| Parameter          | Type   | Required | Description                                  |
| ------------------ | ------ | -------- | -------------------------------------------- |
| `amount`           | number | Yes      | Aggregate payment amount                     |
| `recipientAddress` | string | Yes      | Recipient address                            |
| `resourceUrl`      | string | Yes      | API endpoint URL                             |
| `txHash`           | string | No       | Onchain settlement transaction hash          |
| `credentialId`     | string | No       | MPP credential ID                            |
| `paymentReceipt`   | string | No       | Payment receipt payload                      |
| `batchItems`       | array  | No       | Per-call detail records for batch settlement |

***

## Card Payments (2)

| Tool           | Description                                          |
| -------------- | ---------------------------------------------------- |
| `card_approve` | Request approval for a card payment against policies |
| `card_confirm` | Confirm a card payment was completed                 |

### card\_approve

| Parameter          | Type   | Required | Description                    |
| ------------------ | ------ | -------- | ------------------------------ |
| `cardId`           | string | Yes      | Card ID                        |
| `amount`           | number | Yes      | Transaction amount             |
| `currency`         | string | No       | Currency code (default: "USD") |
| `merchantName`     | string | No       | Merchant name                  |
| `merchantCategory` | string | No       | MCC code                       |
| `purpose`          | string | No       | Purchase purpose               |

### card\_confirm

| Parameter           | Type   | Required | Description                            |
| ------------------- | ------ | -------- | -------------------------------------- |
| `requestId`         | string | Yes      | Payment request ID from `card_approve` |
| `approvalToken`     | string | Yes      | Approval token from `card_approve`     |
| `externalTxId`      | string | No       | External transaction ID                |
| `authorizationCode` | string | No       | Authorization code from card processor |
| `actualAmount`      | number | No       | Actual charged amount                  |

***

## Agent-to-Agent (6)

| Tool                  | Description                                  |
| --------------------- | -------------------------------------------- |
| `a2a_send_request`    | Send a payment request to another agent      |
| `a2a_list_requests`   | List incoming/outgoing A2A requests          |
| `a2a_respond`         | Approve or reject an A2A request             |
| `a2a_execute`         | Execute an approved A2A payment              |
| `a2a_resolve_address` | Check if an address belongs to a Conto agent |
| `a2a_get_stats`       | Get A2A payment statistics                   |

### a2a\_send\_request

| Parameter             | Type   | Required | Description                                  |
| --------------------- | ------ | -------- | -------------------------------------------- |
| `amount`              | number | Yes      | Amount in USDC                               |
| `targetAgentId`       | string | No       | Target agent ID (or use targetWalletAddress) |
| `targetWalletAddress` | string | No       | Target wallet address                        |
| `purpose`             | string | No       | Why this payment is requested                |
| `invoiceId`           | string | No       | Invoice reference ID                         |

### a2a\_respond

| Parameter   | Type   | Required | Description               |
| ----------- | ------ | -------- | ------------------------- |
| `requestId` | string | Yes      | A2A request ID            |
| `action`    | string | Yes      | `'approve'` or `'reject'` |
| `reason`    | string | No       | Optional rejection reason |

***

## Trust & Intelligence (4)

| Tool                  | Description                                        |
| --------------------- | -------------------------------------------------- |
| `check_address_trust` | Get trust score and risk info for a wallet address |
| `list_counterparties` | List known counterparties with trust levels        |
| `get_counterparty`    | Get counterparty details and transaction history   |
| `create_counterparty` | Create or update a counterparty                    |

### create\_counterparty

| Parameter     | Type   | Required | Description              |
| ------------- | ------ | -------- | ------------------------ |
| `name`        | string | Yes      | Counterparty name        |
| `address`     | string | Yes      | Wallet address           |
| `type`        | string | No       | Type (default: 'VENDOR') |
| `category`    | string | No       | Category                 |
| `description` | string | No       | Description              |

***

## Monitoring (4)

| Tool                    | Description                          |
| ----------------------- | ------------------------------------ |
| `list_alerts`           | List active alerts and notifications |
| `get_alert`             | Get details of a specific alert      |
| `respond_to_alert`      | Acknowledge or resolve an alert      |
| `get_approval_requests` | List pending approval requests       |

### list\_alerts

| Parameter  | Type   | Required | Description                                  |
| ---------- | ------ | -------- | -------------------------------------------- |
| `status`   | string | No       | Filter: `ACTIVE`, `ACKNOWLEDGED`, `RESOLVED` |
| `severity` | string | No       | Filter: `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`  |
| `limit`    | number | No       | Results per page (max 100)                   |
| `offset`   | number | No       | Pagination offset                            |

### get\_alert

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `alertId` | string | Yes      | Alert ID    |

### respond\_to\_alert

| Parameter    | Type   | Required | Description                |
| ------------ | ------ | -------- | -------------------------- |
| `alertId`    | string | Yes      | Alert ID                   |
| `action`     | string | Yes      | 'acknowledge' or 'resolve' |
| `resolution` | string | No       | Resolution notes           |

***

## Analytics & Info (7)

| Tool                       | Description                                   |
| -------------------------- | --------------------------------------------- |
| `get_analytics`            | Get spending analytics and trends             |
| `get_policies`             | List spending policies assigned to this agent |
| `request_policy_exception` | Request an exception to a spending policy     |
| `list_policy_exceptions`   | List policy exception requests                |
| `get_agent_info`           | Get information about this agent              |
| `get_all`                  | Get comprehensive agent data in one call      |
| `get_setup`                | Get agent setup and configuration             |

### request\_policy\_exception

| Parameter | Type   | Required | Description                                                                                |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `type`    | string | Yes      | ADD\_TO\_WHITELIST, INCREASE\_SPEND\_LIMIT, EXTEND\_TIME\_WINDOW, ADD\_CATEGORY, or CUSTOM |
| `reason`  | string | Yes      | Why this exception is needed                                                               |
| `urgency` | string | No       | LOW, NORMAL, HIGH, or CRITICAL                                                             |
| `details` | object | No       | Exception details (address, limit, etc.)                                                   |

### get\_all

| Parameter         | Type   | Required | Description                                                                                                                  |
| ----------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `include`         | string | No       | Comma-separated sections: agent, wallets, policies, counterparties, transactions, alerts, analytics, capabilities, endpoints |
| `analyticsPeriod` | string | No       | 'day', 'week', 'month', or 'year'                                                                                            |

***

## Audit & Rate Limits (2)

| Tool              | Description                                 |
| ----------------- | ------------------------------------------- |
| `get_audit_logs`  | Get audit logs of agent actions             |
| `get_rate_limits` | Get current API rate limit status and usage |

### get\_audit\_logs

| Parameter  | Type   | Required | Description                |
| ---------- | ------ | -------- | -------------------------- |
| `action`   | string | No       | Filter by action type      |
| `resource` | string | No       | Filter by resource type    |
| `from`     | string | No       | Start date (ISO string)    |
| `to`       | string | No       | End date (ISO string)      |
| `limit`    | number | No       | Results per page (max 100) |
| `offset`   | number | No       | Pagination offset          |