Skip to main content
A session represents a single deposit attempt. It tracks the full lifecycle from creation through delivery.

​
Session lifecycle

​
Statuses

StatusDescription
requires_payment_methodSession created, waiting for the user to choose how to pay
waiting_paymentPayment method set, waiting for the user’s deposit transaction
processingDeposit detected, funds are being routed to the destination
succeededFunds delivered to the destination address
bouncedDelivery failed (e.g. contract call reverted), funds returned to refund address
expiredSession timed out before a deposit was received
Terminal statuses: succeeded, bounced, expired. Once terminal, a session cannot change status.

​
Credential model

Daimo uses two types of credentials:

​
API key

Your account-wide API key. Use it server-side only for operations that require full access:
  • Creating sessions
  • Retrieving full session details (including clientSecret and metadata)
Pass it as a Bearer token: 
Authorization: Bearer <your API key>

​
Client secret

A per-session token returned when you create a session. It grants limited access to that single session:
  • Setting the payment method
  • Checking session status
The client secret is safe to expose in browser code. Pass it in the request body (or query string for GET requests): 
{ "clientSecret": "d7a8f3b2..." }

​
Session object

When retrieved with an API key, the full session includes:
FieldTypeDescription
sessionIdstringUnique 32-character hex ID
statusstringOne of the statuses above
destinationobjectWhere funds are delivered (see below)
displayobjectUI metadata: title, verb, optional themeCssUrl
paymentMethodobject | nullHow the user is paying (see below)
metadataobject | nullKey-value pairs set at creation
clientSecretstringPer-session client credential
createdAtnumberUnix timestamp (seconds)
expiresAtnumberUnix timestamp (seconds)
Without an API key, metadata and clientSecret are omitted (returns SessionPublicInfo).

​
Destination

{
  type: "evm",
  address: "0x...",       // destination address
  chainId: 8453,          // e.g. Base
  chainName: "Base",
  tokenAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  // e.g. USDC
  tokenSymbol: "USDC",
  amountUnits: "10.00",   // requested amount (optional)
  delivery: {             // set once funds are delivered
    txHash: "0x...",
    receivedUnits: "10.00"
  }
}

​
Payment methods

To collect a deposit, you first set a payment method on the session by calling POST /v1/sessions/{id}/paymentMethods. This transitions the session to waiting_payment and returns the information needed to complete the deposit. Three types, depending on the source chain: EVM Deposit from any of our supported EVM chains. The response includes a single-use receiverAddress in session.paymentMethod. Display this address so the user can send funds to it. 
{ "type": "evm", "receiverAddress": "0x...", "createdAt": 1700000000 }
Tron Deposit USDT from Tron. The response includes a tron.receiverAddress, a single-use Tron address where the user sends USDT. 
{ "type": "tron", "receiverAddress": "T...", "createdAt": 1700000000 }
Solana Deposit from Solana. The response includes solana.serializedTx, a hex-encoded serialized transaction for the wallet to sign and submit. This preserves a one-click wallet flow on Solana by bundling actions into one signed transaction. 
{ "type": "solana", "createdAt": 1700000000 }
Each payment method gains a source object once the user’s deposit transaction is detected, containing chain info, token details, and the source transaction hash. See Create Payment Method for full request/response details.

​
Custom theming with themeCssUrl

Pass a themeCssUrl in display when creating a session to override the default Daimo UI colors, radii, and other visual tokens. The URL should point to a CSS file that redefines any of the --daimo-* custom properties. Example CSS file: 
:root {
  --daimo-bg: #f5f0eb;
  --daimo-surface: #ffffff;
  --daimo-surface-secondary: #faf7f4;
  --daimo-accent: #e85d04;
  --daimo-text: #1a1a1a;
  --daimo-text-secondary: #6b6b6b;
  --daimo-border: #e0dcd7;
  --daimo-radius-lg: 16px;
}
Available custom properties:
PropertyDescription
--daimo-bgPage background
--daimo-surfaceCard / modal background
--daimo-surface-secondarySecondary surface for contrast
--daimo-surface-hoverHover state background
--daimo-textPrimary body text
--daimo-text-secondarySecondary text
--daimo-text-mutedMuted text
--daimo-titleTitle / heading text
--daimo-accentPrimary accent color
--daimo-successSuccess state
--daimo-success-lightSuccess background
--daimo-checkmarkCheckmark / confirmation color
--daimo-errorError state
--daimo-error-lightError background
--daimo-warningWarning state
--daimo-borderBorder color
--daimo-placeholderPlaceholder / inactive
--daimo-skeletonLoading skeleton
--daimo-qr-bgQR code background
--daimo-qr-dotQR code dot color
--daimo-radius-smSmall radius (default 0.5rem)
--daimo-radius-mdMedium radius (default 0.75rem)
--daimo-radius-lgLarge radius (default 1rem)
--daimo-radius-xlExtra-large radius (default 20px)
Host the CSS file on a publicly accessible URL with appropriate CORS headers. The file is loaded dynamically at runtime via a <link> element.

​
Polling for status

Use PUT /v1/sessions/{id}/check with the client secret to poll for status updates after the user has paid. This is how the modal tracks deposit progress, and how custom integrations can monitor sessions from the client side. For most integrations, the modal handles polling automatically.