> ## 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.

# POST /api/ai-sessions — Create a New AI Session

> POST /api/ai-sessions — creates an AI session for a smart account and policy, returning an MCP auth token and on-chain registration parameters.

Create a new AI session to authorize an AI assistant to submit Stellar transactions on your behalf. When you create a session, Pay3 generates an ephemeral session keypair, derives an MCP auth token, and returns a ready-to-paste configuration block for your AI client. You also receive the parameters needed to register the session on-chain via your Soroban smart account contract — this on-chain call activates the session so the Stellar network will accept its signed transactions.

## Endpoint

```
POST /api/ai-sessions
```

## Authentication

All requests must include a valid bearer token in the `Authorization` header, or a `pay3_session` cookie obtained during wallet authentication.

```
Authorization: Bearer <token>
```

## Request body

**smartAccountId** `string` *required*

UUID of the smart account (Soroban contract) that this session will operate on. The account must belong to your user.

**policyId** `string` *required*

UUID of the spending policy to apply to this session. All transactions submitted through this session are evaluated against the policy's budget limits, allowed assets, and approval thresholds.

**clientType** `string` *required*

The AI client you are authorizing. Must be one of: `CURSOR`, `CLAUDE`, `CHATGPT`, `GEMINI`, `OTHER`.

**authorizationTxHash** `string`

*(Optional)* The Stellar transaction hash of the on-chain `add_session` call, if you have already submitted it. You may supply this after the fact by creating the session first and registering on-chain separately.

## Response fields

**id** `string` *required*

Unique UUID for the newly created session.

**mcpAuthToken** `string` *required*

The secret MCP bearer token your AI client will use to authenticate with the Pay3 MCP server. **This value is shown only once** — store it immediately.

**mcpConfig** `object` *required*

Ready-to-use configuration for your AI client's MCP server settings.

**mcpConfig fields**

**apiBaseUrl** `string`

The Pay3 MCP server base URL your client should connect to.

**mcpAuthToken** `string`

Duplicate of the top-level `mcpAuthToken` — included here for convenience so you can paste the entire `mcpConfig` block into your client's configuration.

**stdio** `object`

Configuration for launching the MCP server process directly (for clients that support stdio-mode MCP servers).

**stdio fields**

**command** `string`

The command used to launch the MCP server process.

**args** `array`

Arguments passed to the launch command.

**env** `object`

Environment variables to inject, including `PAY3_MCP_AUTH_TOKEN` set to your session token.

**onChainRegistration** `object`

Parameters for the Soroban `add_session` contract call that activates this session on the Stellar network. You must submit this call — signed by your owner wallet — before the AI can send any transactions. Returns `null` if no smart account contract ID could be resolved.

**onChainRegistration fields**

**contractId** `string`

The Soroban contract address (C-address) of your smart account.

**method** `string`

Always `"add_session"`.

**sessionPublicKey** `string`

The Ed25519 public key of the ephemeral session keypair (Stellar G-address format). This is the key authorized to sign transactions on-chain.

**expiresAtUnix** `number`

Session expiry as a Unix timestamp in seconds. Pass this directly to the `add_session` contract call.

**perTxMax** `string`

Maximum spend per transaction in USD, as a decimal string. Sourced from the linked policy's `perTransactionMax`.

**dailyMax** `string`

Maximum daily spend in USD, as a decimal string. Sourced from the linked policy's `dailyBudget`.

**usdcSacContractId** `string`

Contract address of the USDC Stellar Asset Contract (SAC) used for budget enforcement on-chain.

**note** `string`

Human-readable reminder to sign the `add_session` call with your owner wallet before MCP transfers will be accepted.

**expiresAt** `string` *required*

ISO 8601 timestamp when this session will automatically expire. Determined by the `sessionDurationHours` field of the linked policy.

**status** `string` *required*

Initial status of the session. Always `ACTIVE` on creation.

> [!WARNING]
>
> The `mcpAuthToken` is returned **only once** at session creation and is never stored in plaintext by Pay3. Copy it to your AI client configuration immediately — if you lose it, you must revoke this session and create a new one.

## Example request

```bash theme={null}
curl -X POST https://api.pay3.dev/api/ai-sessions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "smartAccountId": "a1b2c3d4-1234-5678-abcd-ef0123456789",
    "policyId": "f9e8d7c6-dcba-4321-fedc-ba9876543210",
    "clientType": "CURSOR"
  }'
```

## Example response

```json theme={null}
{
  "id": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
  "status": "ACTIVE",
  "mcpAuthToken": "pay3_mcp_ey...<redacted>",
  "mcpConfig": {
    "apiBaseUrl": "https://mcp.pay3.dev",
    "mcpAuthToken": "pay3_mcp_ey...<redacted>",
    "stdio": {
      "command": "node",
      "args": ["apps/mcp-server/dist/index.js"],
      "env": {
        "PAY3_MCP_AUTH_TOKEN": "pay3_mcp_ey...<redacted>"
      }
    }
  },
  "onChainRegistration": {
    "contractId": "CCHD3XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "method": "add_session",
    "sessionPublicKey": "GDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "expiresAtUnix": 1752672600,
    "perTxMax": "100",
    "dailyMax": "500",
    "usdcSacContractId": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",
    "note": "Sign add_session with the owner wallet (Freighter or stellar CLI) before MCP transfers."
  },
  "expiresAt": "2025-07-15T14:30:00.000Z"
}
```

## Error responses

| Status | Meaning |
| - | - |
| `400 Bad Request` | Missing or invalid `smartAccountId`, `policyId`, or `clientType`. |
| `401 Unauthorized` | Missing or invalid bearer token. |
| `404 Not Found` | The specified `smartAccountId` or `policyId` does not exist or does not belong to your account. |

> [!NOTE]
>
> After receiving the response, submit the `onChainRegistration` parameters via Freighter, the Stellar CLI, or your preferred Soroban client. The session exists in Pay3's system immediately, but the AI cannot submit transactions until the smart account contract has recorded the session public key on-chain.


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