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

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

string

required

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

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.

string

required

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

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

string

required

Unique UUID for the newly created session.

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.

object

required

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

Show mcpConfig fields

string

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

string

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

object

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

Show stdio fields

string

The command used to launch the MCP server process.

array

Arguments passed to the launch command.

object

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

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.

Show onChainRegistration fields

string

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

string

Always "add_session".

string

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

number

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

string

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

string

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

string

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

string

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

string

required

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

string

required

Initial status of the session. Always ACTIVE on creation.

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

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

{
  "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.

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.

Authentication

Wallet & Accounts

Sessions & Policies

Transactions

Contacts & Analytics

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

Endpoint

Authentication

Request body

Response fields

Example request

Example response

Error responses

​Endpoint

​Authentication

​Request body

​Response fields

​Example request

​Example response

​Error responses

Endpoint

Authentication

Request body

Response fields

Example request

Example response

Error responses