Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.daimo.com/llms.txt

Use this file to discover all available pages before exploring further.

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. Four types, depending on the source:

​
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 }

​
Fiat

Hosted fiat deposit. The user pays in local currency via one of the fiat rails enabled for your org (e.g. Interac in Canada, ACH and Apple Pay in the US, or SEPA in Europe), and Daimo delivers the stablecoin to your destination — same session lifecycle as any other payment method. The response includes fiat.hostedUrl, a URL to a Daimo-hosted page that handles identity verification and the fiat transfer. Open it in a native WebView or a new browser tab; the user returns to your app after completing the flow. 
{ "type": "fiat", "fiatMethod": "interac", "createdAt": 1700000000 }

{
  "fiat": {
    "hostedUrl": "https://daimo.com/webview?session=...&cs=...",
    "fiatMethod": "interac"
  }
}
Pass paymentMethod.fiatMethod (one of interac, ach, sepa, apple_pay) to pin the hosted flow to one rail. If omitted, the hosted page lists every fiat method enabled for the org. The hostedUrl is returned only once from createPaymentMethod — store it on the client. It is not included when retrieving the session later.
Fiat rails are enabled per-org. To request access, contact us.
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.