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

# Pay3 MCP Tools Reference: balance, transfer, history

> Full reference for the three Pay3 MCP tools — get_balance, transfer, and get_transaction_history — with parameters and example AI prompts.

The Pay3 MCP server registers three tools that your AI assistant can call on your behalf. Every call is authenticated with your session's MCP auth token and evaluated by the Policy Engine before any action is taken on-chain. This page documents each tool's parameters, possible outcomes, and example prompts you can use to trigger them naturally in conversation.

***

## `get_balance`

Returns the current balance of a specific asset held in your Pay3 smart account for the active session.

### Parameters

**asset** `string` *required*

The asset code to query. Must be one of: `USDC`, `XLM`.

The asset code is case-insensitive — `usdc`, `USDC`, and `Usdc` all work.

### Example AI prompts

* *"What is my USDC balance?"*
* *"How much XLM do I have in my Pay3 wallet?"*
* *"Check my balance before I send a payment."*

### Example response

```json theme={null}
{
  "asset": "USDC",
  "balance": "245.50",
  "sessionId": "ses_abc123",
  "smartAccountId": "sma_xyz789",
  "source": "soroban_vault"
}
```

### Response fields

**asset** `string`

The normalised asset code you queried, e.g. `"USDC"`.

**balance** `string`

The current balance as a decimal string, e.g. `"245.50"`.

**sessionId** `string`

The ID of the AI session that made the request.

**smartAccountId** `string`

The Pay3 smart account ID associated with this session.

**source** `string`

Where the balance was read from. `"soroban_vault"` for USDC via the on-chain vault contract; `"horizon"` for XLM and other assets queried directly from the Stellar network.

***

## `transfer`

Initiates a payment from your Pay3 smart account to a recipient. Before the transaction is submitted to Stellar, it passes through the Policy Engine and resolves the recipient address. Depending on your session's policy configuration, the transfer is either auto-executed, queued for your manual approval, or rejected.

### Parameters

**recipient** `string` *required*

The destination for the payment. Accepts:

* A full Stellar public key (`G...`)
* A verified contact name or alias saved in your Pay3 account (e.g. `"Alice"`)

**asset** `string` *required*

The asset to send. Must be one of: `USDC`, `XLM`.

**amount** `string` *required*

The amount to send, expressed as a decimal string. Examples: `"5"`, `"10.00"`, `"0.50"`.

**idempotency\_key** `string` *required*

A stable, unique key for this payment intent (8–128 characters). If you retry the same transfer, reuse the exact same key — Pay3 will recognise the duplicate and return the original result instead of submitting a second transaction. Generate a UUID per payment attempt, or use a meaningful identifier like `"order-789-payment-1"`.

### Execution outcomes

Every `transfer` call produces one of three outcomes:

> **AUTO\_EXECUTE**
>
> The transfer passed all policy checks and was submitted to Stellar immediately. The response includes the Stellar transaction hash.

> **PENDING\_APPROVAL**
>
> The transfer exceeded a threshold in your policy (e.g. single-transaction limit) and is queued for your manual approval in the Pay3 Dashboard. You have **2 minutes** to approve or reject it.

> **REJECTED**
>
> The transfer violated a policy rule — daily budget exceeded, asset not allowed, session expired, etc. The response explains which rule was violated.

### Example AI prompts

* *"Send 5 USDC to Alice."*
* *"Pay Bob 0.50 XLM for the API call."*
* *"Transfer 100 USDC to GABCDE...XYZ."*
* *"Pay the supplier 200 USDC. Use idempotency key order-1234."*
* *"Send 50 XLM to my contact named Dev Fund."*

### Example responses

**Success (AUTO\_EXECUTE)**

```json theme={null}
{
  "status": "SUCCESS",
  "transactionId": "txn_abc123",
  "stellarHash": "abc123...def456",
  "amount": "5.00",
  "asset": "USDC",
  "recipient": "GABCDE...XYZ"
}
```

**Pending Approval**

```json theme={null}
{
  "status": "PENDING_APPROVAL",
  "transactionId": "txn_xyz789",
  "message": "Payment requires manual approval in the Pay3 dashboard. The approval request expires in 2 minutes."
}
```

> [!WARNING]
>
> If you do not approve the transaction in the Pay3 Dashboard within **2 minutes**, the request expires and the transfer is cancelled. Ask your AI assistant to retry if needed.

**Rejected**

```json theme={null}
{
  "status": "REJECTED",
  "rejectionReason": "Daily budget of 500 USDC has been reached for this session."
}
```

The `rejectionReason` field always explains which policy rule blocked the transfer.

### Response fields

**status** `string`

One of `SUCCESS`, `PENDING_APPROVAL`, or `REJECTED`.

**transactionId** `string`

Pay3's internal transaction ID. Use this to look up the transaction in the Dashboard.

**stellarHash** `string`

The Stellar network transaction hash. Present only when `status` is `SUCCESS`. Use this to verify the transaction on a Stellar explorer.

**amount** `string`

The amount that was sent, as a decimal string. Present on success.

**asset** `string`

The asset that was sent. Present on success.

**recipient** `string`

The resolved Stellar address of the recipient. Present on success.

**message** `string`

A human-readable message. Present when `status` is `PENDING_APPROVAL`.

**rejectionReason** `string`

Explanation of which policy rule blocked the transfer. Present when `status` is `REJECTED`.

***

## `get_transaction_history`

Returns the most recent transactions recorded for the current AI session, sorted newest-first.

> [!NOTE]
>
> `get_transaction_history` only returns transactions made **within the current session**. Transactions from other sessions — including previous sessions on the same account — are not included. To view your full cross-session history, open the Pay3 Dashboard.

### Parameters

**limit** `number`

The maximum number of transactions to return. Must be between `1` and `50`. Defaults to `20` if omitted.

### Example AI prompts

* *"Show me my last 10 transactions."*
* *"What payments have I made today?"*
* *"Did my transfer to Alice go through?"*

### Example response

```json theme={null}
{
  "transactions": [
    {
      "id": "txn_abc123",
      "action": "TRANSFER",
      "asset": "USDC",
      "amount": "5.00",
      "recipientInput": "Alice",
      "recipientAddress": "GABCDE...XYZ",
      "status": "SUCCESS",
      "policyDecision": "AUTO_EXECUTE",
      "stellarTransactionHash": "abc123...def456",
      "createdAt": "2025-01-15T10:30:00Z",
      "completedAt": "2025-01-15T10:30:05Z"
    },
    {
      "id": "txn_def456",
      "action": "TRANSFER",
      "asset": "XLM",
      "amount": "0.50",
      "recipientInput": "Bob",
      "recipientAddress": "GHIJK...LMN",
      "status": "PENDING_APPROVAL",
      "policyDecision": "PENDING_APPROVAL",
      "stellarTransactionHash": null,
      "createdAt": "2025-01-15T10:28:00Z",
      "completedAt": null
    }
  ]
}
```

### Response fields

**transactions** `array`

An array of transaction objects, sorted newest-first.

**Transaction object fields**

**id** `string`

Pay3's internal transaction ID.

**action** `string`

The type of action. Currently `TRANSFER`.

**asset** `string`

The asset involved, e.g. `"USDC"` or `"XLM"`.

**amount** `string`

The transaction amount as a decimal string.

**recipientInput** `string`

The original recipient value your AI assistant provided (e.g. a contact name like `"Alice"`).

**recipientAddress** `string`

The resolved Stellar public key of the recipient.

**status** `string`

Current transaction status: `SUCCESS`, `PENDING_APPROVAL`, `REJECTED`, or `FAILED`.

**policyDecision** `string`

The Policy Engine's decision: `AUTO_EXECUTE`, `PENDING_APPROVAL`, or `REJECTED`.

**stellarTransactionHash** `string`

The Stellar network transaction hash. `null` if the transaction has not yet been submitted.

**createdAt** `string`

ISO 8601 timestamp when the transaction was created.

**completedAt** `string`

ISO 8601 timestamp when the transaction reached a terminal state. `null` if still pending.

***

## Tool availability by policy

Some tools require specific permissions to be enabled in your session's policy. If your session's policy does not permit an action, the tool call returns a policy error immediately — nothing is submitted to the network.

| Tool | Required permission |
| - | - |
| `get_balance` | Balance read allowed |
| `transfer` | Transfer allowed |
| `get_transaction_history` | History read allowed |

> [!TIP]
>
> Review and update your session's policy settings in the **Sessions** section of the [Pay3 Dashboard](https://pay3.finance/dashboard/sessions).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.