Attach a source to a flow and mint a session token

Sets the source wallet address and chain on a flow and mints the capability sessionToken used to drive the rest of the lifecycle. No API key or token is required (the browser has neither at this point) — the endpoint is gated by the flow’s state and by CORS. A source can be attached while the flow is initiated, source_attached, quoted or signing, so a payer can switch source before broadcasting. Unlike quote, prepare, broadcast and cancel, which always require the session token, attach needs no token for the first attach or while the flow is source_attached or quoted. From signing, the current session token must be supplied (X-Dynamic-Flow-Session-Token) to prove the caller is the original signer; otherwise the request is rejected with 403 session_token_invalid. Once the flow has been broadcasted or source_detected, or has reached a terminal state, the request is rejected with 409 flow_invalid_transition. Each attach mints a new session token and invalidates the previous one, so at most one live token exists per flow at a time.

POST /sdk/{environmentId}/flow/{flowId}/source

Attach a source to a flow and mint a session token

cURL

curl --request POST \
  --url https://app.dynamicauth.com/api/v0/sdk/{environmentId}/flow/{flowId}/source \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fromAddress": "0xbF394748301603f18d953C90F0b087CBEC0E1834",
  "fromChainId": "An example name",
  "refundAddress": "0xbF394748301603f18d953C90F0b087CBEC0E1834"
}
'

200

{
  "sessionExpiresAt": "2023-11-07T05:31:56Z",
  "sessionToken": "dft_A1B2C3...",
  "flow": {
    "id": "95b11417-f18f-457f-8804-68e361f9164f",
    "mode": "payment",
    "amount": "<string>",
    "currency": "An example name",
    "executionState": "initiated",
    "settlementState": "none",
    "riskState": "unknown",
    "quoteVersion": 123,
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "amountUsd": "<string>",
    "currencyTokenInfo": {
      "symbol": "<string>",
      "decimals": 123,
      "name": "<string>",
      "logoURI": "<string>"
    },
    "memo": {},
    "userId": "95b11417-f18f-457f-8804-68e361f9164f",
    "sourceType": "wallet",
    "fromAddress": "0xbF394748301603f18d953C90F0b087CBEC0E1834",
    "fromChainId": "An example name",
    "fromChainName": "ETH",
    "fromToken": "An example name",
    "toAddress": "0xbF394748301603f18d953C90F0b087CBEC0E1834",
    "toChainId": "An example name",
    "toChainName": "ETH",
    "toToken": "An example name",
    "quote": {
      "version": 123,
      "fromAmount": "<string>",
      "toAmount": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "expiresAt": "2023-11-07T05:31:56Z",
      "fees": {
        "totalFeeUsd": "<string>",
        "gasEstimate": {
          "usdValue": "<string>",
          "nativeValue": "<string>",
          "nativeSymbol": "<string>"
        }
      },
      "estimatedTimeSec": 123,
      "signingPayload": {
        "chainName": "ETH",
        "chainId": "<string>",
        "evmTransaction": {
          "to": "<string>",
          "data": "<string>",
          "value": "<string>",
          "gasLimit": "<string>",
          "gasPrice": "<string>",
          "maxFeePerGas": "<string>",
          "maxPriorityFeePerGas": "<string>",
          "nonce": 123
        },
        "evmApproval": {
          "tokenAddress": "<string>",
          "spenderAddress": "<string>",
          "amount": "<string>"
        },
        "serializedTransaction": "<string>",
        "psbt": "<string>",
        "tronTransaction": {
          "rawDataHex": "<string>",
          "to": "<string>",
          "value": "<string>"
        }
      },
      "fromChainName": "ETH",
      "fromChainId": "An example name",
      "fromToken": "An example name",
      "toChainName": "ETH",
      "toChainId": "An example name",
      "toToken": "An example name",
      "fromTokenInfo": {
        "symbol": "<string>",
        "decimals": 123,
        "name": "<string>",
        "logoURI": "<string>"
      },
      "toTokenInfo": {
        "symbol": "<string>",
        "decimals": 123,
        "name": "<string>",
        "logoURI": "<string>"
      }
    },
    "txHash": "<string>",
    "settlementTxHash": "<string>",
    "broadcastedAt": "2023-11-07T05:31:56Z",
    "sourceConfirmedAt": "2023-11-07T05:31:56Z",
    "confirmations": 123,
    "settlement": {
      "toChainId": "An example name",
      "toToken": "An example name",
      "toAddress": "0xbF394748301603f18d953C90F0b087CBEC0E1834",
      "completedAt": "2023-11-07T05:31:56Z",
      "amount": "<string>",
      "amountUsd": "<string>",
      "toTokenInfo": {
        "symbol": "<string>",
        "decimals": 123,
        "name": "<string>",
        "logoURI": "<string>"
      }
    },
    "completedAt": "2023-11-07T05:31:56Z",
    "failure": {
      "code": "An example name",
      "message": "<string>",
      "category": "An example name",
      "stage": "An example name",
      "retryable": true,
      "details": {}
    },
    "expiresAt": "2023-11-07T05:31:56Z",
    "depositAddress": "0xbF394748301603f18d953C90F0b087CBEC0E1834",
    "exchangeSource": {
      "exchangeId": "95b11417-f18f-457f-8804-68e361f9164f",
      "metadata": {}
    },
    "pegStablecoins": true,
    "disableSwaps": true,
    "uiConfig": {
      "returnUrl": "<string>",
      "termsOfServicesUrl": "https://website-sample.com",
      "merchantName": "An example name",
      "merchantLogoUrl": "https://website-sample.com/logo.png",
      "externalPaymentId": "An example name",
      "enabledPaymentMethods": [
        "wallet"
      ]
    },
    "settlementConfig": {
      "strategy": "cheapest",
      "settlements": [
        {
          "chainName": "ETH",
          "tokenAddress": "An example name",
          "chainId": "An example name",
          "symbol": "An example name",
          "tokenDecimals": 18,
          "isNative": true
        }
      ]
    },
    "destinationConfig": {
      "destinations": [
        {
          "chainName": "ETH",
          "type": "address",
          "identifier": "An example name"
        }
      ]
    }
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Dynamic-Flow-Session-Token · string

Flow session token issued at source attachment. Format: dft_. Required when no JWT is provided, except on attachFlowSource, where it is required only when re-attaching from the signing state.

Path Parameters

environmentId · string · required

ID of the environment

Required string length: 36

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"95b11417-f18f-457f-8804-68e361f9164f"

flowId · string · required

UUID of the flow

Required string length: 36

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"95b11417-f18f-457f-8804-68e361f9164f"

Body

application/json

fromAddress, fromChainId, and fromChainName are required when sourceType is 'wallet'. When sourceType is 'exchange', they are optional; pass exchangeProvider to generate the buy URL and create the exchange source record server-side. When sourceType is 'deposit_address', fromChainId, fromChainName, and refundAddress are all required (refundAddress specifies where funds should be returned if the deposit fails); fromAddress is not accepted.

sourceType · enum<string> · required

How a flow is funded — a connected wallet, a CEX, or a deposit address.

Available options: wallet, exchange, deposit_address

fromAddress · string

Valid blockchain wallet address, must be an alphanumeric string (underscores allowed for chains like Midnight, hyphens allowed for chains using base64url-encoded addresses like TON)

Maximum string length: 255

Pattern: ^[A-Za-z0-9_-]{18,100}$

Example:

"0xbF394748301603f18d953C90F0b087CBEC0E1834"

fromChainId · string

Maximum string length: 50

Pattern: ^(?=\S)[\p{L}\p{N}a-zA-Z _.,:!?&%@\/+\-'|]+(?<=\S)$

Example:

"An example name"

fromChainName · enum<string>

Available options: ETH, EVM, FLOW, SOL, ALGO, STARK, COSMOS, BTC, ECLIPSE, SUI, SPARK, TRON, APTOS, TON, STELLAR, ALEO, TEMPO, MIDNIGHT

exchangeProvider · enum<string>

Source exchange identifier

Available options: coinbase, kraken, gemini, binance

refundAddress · string

Valid blockchain wallet address, must be an alphanumeric string (underscores allowed for chains like Midnight, hyphens allowed for chains using base64url-encoded addresses like TON)

Maximum string length: 255

Pattern: ^[A-Za-z0-9_-]{18,100}$

Example:

"0xbF394748301603f18d953C90F0b087CBEC0E1834"

Response

200

application/json

Source attached; session token minted

Response from the source endpoint — carries the one-time capability session token plus the current flow state.

sessionExpiresAt · string<date-time> · required

When the session token expires.

sessionToken · string · required

Opaque capability token for authenticating subsequent calls on this flow (quote, prepare, broadcast, cancel). Minted by the source endpoint and returned exactly once — store it immediately. At most one live token exists per flow at a time. Format: dft_.

Example:

"dft_A1B2C3..."

flow · object · required

A single payment, deposit, or withdraw flow. Collapses the former Checkout and CheckoutTransaction into one resource.

Show child attributes