> ## 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 Quickstart: Your First AI-Powered USDC Payment

> Connect your Freighter wallet, link a smart account, set a spending policy, and make your first AI-powered USDC payment on Stellar in minutes.

Pay3 gives your AI assistant a secure, policy-controlled wallet on Stellar — so it can check balances, send payments, and interact with DeFi on your behalf without ever touching your private key. This guide walks you through everything from wallet setup to your first AI-initiated transfer.

> [!NOTE]
>
> This guide uses the **Stellar testnet**. No real funds are required. When you're ready to move to mainnet, repeat the same steps using a funded mainnet account and switch the network in Freighter.

**1. Set up prerequisites**

Before you begin, make sure you have the following ready.

**Freighter wallet**

Freighter is the official Stellar browser extension wallet. Install it from the [Freighter website](https://www.freighter.app/) and create or import a Stellar account.

**A funded Stellar testnet account**

Your testnet account needs two assets:

* **XLM** — to pay Stellar network transaction fees (a small amount is enough)
* **USDC** — the stablecoin Pay3 uses for payments

Use the [Stellar Laboratory Friendbot](https://laboratory.stellar.org/#account-creator?network=test) to fund your testnet account with XLM. Then add a USDC trustline and claim testnet USDC from a faucet.

> [!TIP]
>
> The Stellar testnet USDC issuer is `GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5`. Add this as a trustline in Freighter before trying to receive testnet USDC.

**2. Sign in to the Pay3 dashboard**

Pay3 authenticates you using a cryptographic challenge — your private key never leaves Freighter.

1. Navigate to [app.pay3.finance](https://app.pay3.finance) and click **Connect Freighter**.
2. Freighter will prompt you to approve the connection — click **Connect**.
3. Pay3 issues a one-time challenge message. Freighter will ask you to sign it — click **Sign**.
4. You're redirected to the dashboard.

> [!NOTE]
>
> If Freighter shows a "connection not secure" warning on localhost, go to **Settings → Security → Advanced** in Freighter and enable insecure domains, then retry.

**3. Link a smart account**

A **smart account** is a Soroban vault contract deployed on Stellar. It holds the USDC your AI is allowed to spend, and it enforces hard on-chain limits that the AI cannot bypass — even if the off-chain policy is misconfigured.

1. In the dashboard sidebar, go to **Sessions**.
2. Under **Link smart account**, paste your Soroban contract ID (a string starting with `C`).
3. Click **Link contract**.

Your linked contract ID appears in the list below the form once confirmed.

> [!NOTE]
>
> Don't have a Soroban vault contract yet? You can deploy the open-source Pay3 vault contract from the [contracts/smart-account](https://github.com/debuuuuuu/PAY3/tree/main/contracts/smart-account) directory, or contact the Pay3 team for a testnet deployment.

**4. Create a spending policy**

A **policy** defines exactly what your AI session is allowed to do: how much it can spend per day, how much per transaction, which assets it can use, and at what amount it must ask for your manual approval.

1. In the dashboard sidebar, go to **Policies**.
2. Give your policy a name (e.g. `My first policy`).
3. Choose a **preset** from the table below, or select **Custom** to set your own values.
4. Click **Create policy**.

| Preset | Daily limit | Per-tx limit | Approval threshold | Session length | Allowed assets |
| - | - | - | - | - | - |
| **CONSERVATIVE** | \$100 | \$20 | \$15 | 24 hours | USDC, XLM |
| **BALANCED** | \$500 | \$100 | \$250 | 168 hours | USDC, XLM |
| **DEFI** | \$1,000 | \$250 | \$500 | 168 hours | USDC, XLM |
| **CUSTOM** | You choose | You choose | You choose | You choose | You choose |

> [!TIP]
>
> Start with **CONSERVATIVE** for your first session. You can always create a more permissive policy later once you're comfortable with how the approval flow works.

**5. Create an AI session and configure your client**

A **session** connects your smart account and policy to a specific AI client, and produces an MCP auth token your AI uses to authenticate every tool call.

**Create the session**

1. Still in **Sessions**, scroll to **Create session**.
2. Select your linked smart account and the policy you just created.
3. Choose your AI client: **Cursor**, **Claude**, **ChatGPT**, **Gemini**, or **Other**.
4. Click **Create AI session**.

A panel appears with your **MCP auth token** and a ready-to-use **mcpConfig** JSON block. Copy both — the token is shown only once.

**Add the config to your AI client**

Paste the `mcpConfig` into your client's settings file. The JSON looks like this:

```json mcpConfig theme={null}
{
  "mcpServers": {
    "pay3": {
      "command": "npx",
      "args": ["-y", "@pay3/mcp-server"],
      "env": {
        "PAY3_MCP_AUTH_TOKEN": "<your-token-here>",
        "API_BASE_URL": "https://api.pay3.finance"
      }
    }
  }
}
```

```json Claude Desktop (claude_desktop_config.json) theme={null}
{
  "mcpServers": {
    "pay3": {
      "command": "npx",
      "args": ["-y", "@pay3/mcp-server"],
      "env": {
        "PAY3_MCP_AUTH_TOKEN": "<your-token-here>",
        "API_BASE_URL": "https://api.pay3.finance"
      }
    }
  }
}
```

```json Cursor (settings.json) theme={null}
{
  "mcpServers": {
    "pay3": {
      "command": "npx",
      "args": ["-y", "@pay3/mcp-server"],
      "env": {
        "PAY3_MCP_AUTH_TOKEN": "<your-token-here>",
        "API_BASE_URL": "https://api.pay3.finance"
      }
    }
  }
}
```

**Where to put the file**

> **Claude Desktop**
>
> Edit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Restart Claude Desktop after saving.

> **Cursor**
>
> Open **Cursor → Settings → MCP** and paste the `mcpServers` block, or edit `~/.cursor/mcp.json` directly. Reload the window after saving.

> [!WARNING]
>
> Treat your MCP auth token like a password. Anyone who has it can initiate payments up to your policy limits. If you believe a token is compromised, go to **Sessions** in the dashboard and click **Revoke** immediately.

**6. Make your first AI payment**

With the MCP server connected, ask your AI assistant to check your balance:

```text Prompt theme={null}
What is my USDC balance?
```

Your AI calls the `get_balance` tool through Pay3 and returns your current USDC balance from the linked smart account. If that works, try a small test transfer:

```text Prompt theme={null}
Send 1 USDC to GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37
```

Because the amount is below the approval threshold on a CONSERVATIVE policy, Pay3 auto-executes the transaction and returns a Stellar transaction hash as proof. You can verify it instantly on [Stellar Expert](https://stellar.expert/explorer/testnet).

> [!NOTE]
>
> If the transfer amount is above your policy's **approval threshold**, Pay3 queues it for manual approval in the dashboard instead of executing immediately. Head to **Sessions** to approve or reject it. Approval requests expire after **2 minutes**.

## What's next?

> **[How It Works](https://pay3.mintlify.site/how-it-works.md)**
>
> Understand the full payment flow, session key security model, and the three-level execution engine.

> **[Policy Reference](https://pay3.mintlify.site/dashboard/policies.md)**
>
> Learn every field available in a custom policy and how the budget accounting works across sessions.

> **[MCP Tools](https://pay3.mintlify.site/mcp/tools.md)**
>
> Browse all tools your AI can call: `get_balance`, `transfer`, `get_transaction_history`, and more.

> **[Session Key Security](https://pay3.mintlify.site/how-it-works.md#session-key-security-model)**
>
> Deep dive into how Pay3 keeps your private key safe while giving your AI delegated permissions.


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