Sessions

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

Session lifecycle

Statuses

Status	Description
`requires_payment_method`	Session created, waiting for the user to choose how to pay
`waiting_payment`	Payment method set, waiting for the user’s deposit transaction
`processing`	Deposit detected, funds are being routed to the destination
`succeeded`	Funds delivered to the destination address
`bounced`	Delivery failed (e.g. contract call reverted), funds returned to refund address
`expired`	Session 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": "1f56acb2-c3d0-4632-98be-e5b2b9a4c1de" }

Session object

When retrieved with an API key, the full session includes:

Field	Type	Description
`sessionId`	`string`	Unique 32-character hex ID
`status`	`string`	One of the statuses above
`destination`	`object`	Where funds are delivered (see below)
`display`	`object`	UI metadata: `title`, `verb`
`paymentMethod`	`object \| null`	How the user is paying (see below)
`metadata`	`object \| null`	Key-value pairs set at creation
`clientSecret`	`string`	Per-session client credential
`createdAt`	`number`	Unix timestamp (seconds)
`expiresAt`	`number`	Unix 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"
  }
}

Deposits can also be delivered to Solana (USDC only):

{
  type: "solana",
  address: "7xKX...",     // base58 destination address
  tokenAddress: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  // USDC mint
  tokenSymbol: "USDC",
  amountUnits: "10.00",   // requested amount (optional)
  delivery: {             // set once funds are delivered
    txHash: "5Uu...",     // Solana transaction signature
    receivedUnits: "10.00"
  }
}

A Solana destination uses the token mint as tokenAddress, omits chainId, chainName, and calldata, and its delivery.txHash is a Solana transaction signature.

Payment methods

Choose the payment method experience when creating the session with display.paymentMethods:

{ "mode": "auto" } shows Daimo’s localized payment picker. This is the recommended default.
{ "mode": "fixed", "type": … } pins the session to one method and skips the picker.

Use paymentMethods for new integrations; it supersedes the legacy display.paymentOptions array. After the user chooses a method (or enters a fixed flow), the modal calls POST /v1/sessions/{id}/paymentMethods. This records the concrete method, transitions the session to waiting_payment, and returns the information needed to complete the deposit. If you build your own UI, call this endpoint directly. The payment instructions depend on the concrete method. Common response shapes are shown below.

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. It can also include tron.deeplinks.trustWallet, a Trust Wallet send link for the same address and amount.

{ "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. With paymentMethods: { mode: "auto" }, eligible fiat rails enabled for your org appear automatically in the user’s localized picker. To offer exactly one rail, set display.paymentMethods to a fixed selector when creating the session:

{ "mode": "fixed", "type": "Interac" }

The user pays in local currency and Daimo delivers the stablecoin to your destination using the same lifecycle as every 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"
  }
}

For a custom UI, call POST /paymentMethods with { "type": "fiat" } and optionally a concrete fiatMethod. A fixed session requires the matching method (for example, fixed Interac requires fiatMethod: "interac"). An auto session may omit fiatMethod to let the hosted page show the enabled rails. See Fiat for the request and response, fixed type mapping, and supported rails. 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.

Customization

Use the Daimo dashboard to match the modal and hosted WebView to your brand. The org theme applies automatically when the deposit UI loads a session for your org. See Customization for the dashboard flow and JSON format.

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.

Getting Started

Accept Deposits

Withdrawals

Advanced

Resources

Session lifecycle

Statuses

Credential model

API key

Client secret

Session object

Destination

Payment methods

EVM

Tron

Solana

Fiat

Customization

Polling for status

​Session lifecycle

​Statuses

​Credential model

​API key

​Client secret

​Session object

​Destination

​Payment methods

​EVM

​Tron

​Solana

​Fiat

​Customization

​Polling for status

Session lifecycle

Statuses

Credential model

API key

Client secret

Session object

Destination

Payment methods

EVM

Tron

Solana

Fiat

Customization

Polling for status