Skip to main content
POST
/
modal
/
sessions
curl --request POST \
  --url https://api.chainrails.io/api/v1/modal/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "recipient": "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
  "tokenOut": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "destinationChain": "STARKNET_MAINNET",
  "amount": "1"
}
'
{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2025-12-24T13:45:30.000Z",
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Corp",
    "email": "contact@acme.com",
    "paymasterEnabled": false,
    "logoUrl": "https://acme.com/logo.png"
  }
}

Authorizations

​
Authorization
string
header
required

Enter your Chainrails API key as a Bearer token

Body

application/json
​
recipient
string
required

Recipient wallet address on the destination chain

Example:

"0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7"

​
tokenOut
string
required

Token address on the destination chain

Example:

"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"

​
destinationChain
enum<string>
required

Destination blockchain network

Available options:
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
Example:

"STARKNET_MAINNET"

​
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

Example:

"1"

Response

Session created successfully

​
sessionId
string
required

Unique session identifier

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
sessionToken
string
required

JWT session token for authentication

Example:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
expiresAt
string<date-time>
required

Token expiration timestamp

Example:

"2025-12-24T13:45:30.000Z"

​
client
object

Client details associated with this session