---
title: "Create a modal session"
method: POST
path: "/modal/sessions"
tags: ["Modal Sessions"]
---

# Create a modal session

`POST /modal/sessions`

Creates a modal session with constraints (recipient, token, chain, amount). Returns a session token valid for 60 minutes.

## Request body

- CreateSessionDto
  - `recipient` string, required — Recipient wallet address on the destination chain
  - `tokenOut` string, required — Token address on the destination chain
  - `destinationChain` 'ARBITRUM_MAINNET' | 'ARBITRUM_TESTNET' | 'AVALANCHE_MAINNET' | 'AVALANCHE_TESTNET' | 'BASE_MAINNET' | 'BASE_TESTNET' | 'STARKNET_MAINNET' | 'STARKNET_TESTNET' | 'BSC_MAINNET' | 'ETHEREUM_MAINNET' | 'ETHEREUM_TESTNET' | 'OPTIMISM_MAINNET' | 'OPTIMISM_TESTNET' | 'MONAD_MAINNET' | 'MONAD_TESTNET' | 'POLYGON_MAINNET' | 'HYPEREVM_MAINNET' | 'LISK_MAINNET' | 'SOLANA_MAINNET' | 'SOLANA_TESTNET' | 'TRON_MAINNET', required — Source blockchain network for the deposit
  - `amount` string, required — Amount in human-readable format (e.g., "1" for 1 token, "100" for 100 tokens, "1.5" for 1.5 tokens). Set to "0" to allow user to input any amount > 0

## Response `201`

Session created successfully

- CreateSessionResponseDto
  - `sessionId` string, required — Unique session identifier
  - `sessionToken` string, required — JWT session token for authentication
  - `expiresAt` string, date-time, required — Token expiration timestamp
  - `client` ClientInfoResponseDto
    - `id` string, required — Client unique identifier
    - `name` string, required — Client name
    - `email` string, required — Client email address
    - `logoUrl` string — Client logo URL
    - `paymasterEnabled` boolean, required — Whether paymaster is enabled for this client
    - `merchantKybVerified` boolean, required — Whether merchant KYB has been verified for live fiat ramp usage

## Other responses

- `401` — Unauthorized - Invalid API key

## Changes

- **2026-07-22** `76a4e00b118d` — 4 info
  - added the new `SOLANA_MAINNET` enum value to the request property `destinationChain/allOf[#/components/schemas/Chains]/`
  - added the new `SOLANA_TESTNET` enum value to the request property `destinationChain/allOf[#/components/schemas/Chains]/`
  - added the new `TRON_MAINNET` enum value to the request property `destinationChain/allOf[#/components/schemas/Chains]/`
  - added the required property `client/allOf[#/components/schemas/ClientInfoResponseDto]/merchantKybVerified` to the response with the `201` status
- **2026-04-09** `654264f49b4d` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/horuslabsio/apis/chainrails-api/changes/modal/sessions/post.md)

---

[API](https://skmtc.dev/horuslabsio/apis/chainrails-api.md) · [All operations](https://skmtc.dev/horuslabsio/apis/chainrails-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/horuslabsio/chainrails-api/revisions/dcf19c1bab20/schema)