Sessions

Understand the lifecycle of a Glide session

A session represents one intent to move money through Glide: someone pays with one token on one chain, and Glide settles with a (possibly different) token on a (possibly different) chain. Every flow — payments, deposits, withdrawals, payouts — creates a session with createSession or createPaymentSession, and everything you need to track it lives on the session object.

A session is valid for a limited time (generally 10 minutes, see expiresAt). If the payment isn't completed in time, the session expires and a new one must be created. A payment made to an expired session is refunded.

The two sides of a session

Session fields are grouped by prefix, and understanding the naming makes the whole object readable:

Prefix	Side	Meaning
`payment*`	payment	What the payer is quoted: currency, chain, amount, and the transaction they make
`sponsoredTransaction*`	settlement	The transaction Glide executes on the destination chain on your behalf — what the recipient receives
`actualPayment*`	payment	Set when the payer pays with a different account or currency than quoted — these override the `payment*` fields
`gasRefuel*`	settlement	The optional gas top-up sent to the recipient on the destination chain
`refund*`	payment	Set when a payment is refunded

"Sponsored transaction" is Glide's term for the settlement: Glide sponsors (executes and pays gas for) the destination-chain transaction, whether that's a contract call or a simple transfer to the recipient.

Payment status

paymentStatus tracks the payer's side:

unpaid ──► waiting_confirmations ──► paid
                                      │
                     pending_refund ◄─┘ (overpaid / underpaid / expired)
                            │
                            ▼
                        refunded

unpaid — the session was created and is waiting for the payment.
waiting_confirmations — the payment transaction was detected and is waiting for chain confirmations.
paid — the payment is confirmed. Settlement proceeds.
pending_refund — the payment can't be settled (for example, the amount was insufficient or the session had expired) and a refund is queued.
refunded — the refund was sent. See refundTransactionHash and refundTransactionUrl.

Settlement status

sponsoredTransactionStatus tracks Glide's destination-chain transaction:

created ──► signed ──► submitted ──► pending ──► success
                                        │
                                        ├──► failed
                                        └──► dropped

Treat success as the single signal that money has arrived — at that point sponsoredTransactionHash and sponsoredTransactionUrl are set. failed and dropped are terminal failure states; waitForSession surfaces them as a SponsoredTransactionFailedError.

Payment actions

When a session is created, paymentAction tells you what the payer must do:

signAndSendTransaction — send unsignedTransaction (EVM) or unsignedSolanaTransaction (Solana) from their wallet.
signTypedData — sign unsignedTypedData for a gasless permit-based payment.
redirectToUrl — complete the payment at redirectUrl (e.g., an onramp).
transfer — send funds to depositAddress from any wallet or exchange.

For connected wallets, executeEVMSession handles the first two actions end to end.

Chain and currency identifiers

Glide identifies chains with CAIP-2 IDs and assets with CAIP-19 IDs, so a single format works across EVM, Solana, Bitcoin, and more:

eip155:8453                                                    // Base (CAIP-2)
eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913   // USDC on Base (CAIP-19)
eip155:1/slip44:60                                             // Native ETH on Ethereum
solana:101/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v  // USDC on Solana

You rarely need to construct these by hand — use the chain and currency helpers:

import { base } from "@paywithglide/glide-js/chains";
import { usdc } from "@paywithglide/glide-js/currencies";
 
base.id;         // "eip155:8453"
usdc.on(base);   // "eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"

For working with IDs you receive back from Glide, the SDK exports three helpers:

import {
  getEIP155ChainId,
  caip2FromCAIP19,
  erc20AddressFromCAIP19,
} from "@paywithglide/glide-js";
 
// Numeric EVM chain ID, e.g. for wallet chain switching.
// Throws for non-EVM IDs.
getEIP155ChainId(session.paymentCurrency); // 8453
 
// The CAIP-2 chain ID of an asset
caip2FromCAIP19(session.paymentCurrency); // "eip155:8453"
 
// The token contract address of an ERC-20 asset.
// Throws for non-ERC-20 IDs (e.g., native currencies).
erc20AddressFromCAIP19(session.paymentCurrency); // "0x8335...2913"

Fees

All fees are quoted upfront on the session, denominated in USD:

serviceFeeUSD — Glide's service fee.
gasFeeUSD — the estimated destination-chain gas, paid by Glide.
paymentTransactionGasFeeUSD — the gas the payer pays for their own payment transaction.
totalFeeUSD — the total, including any developer commission.