Attach a source to a flow and mint a session token

Sets the source wallet address and chain on an initiated 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 still being initiated and by CORS. At most one live token exists per flow at a time. When re-attaching from the signing state, the existing session token must be supplied to prove the caller is the original signer.

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"
}
'

import requests

url = "https://app.dynamicauth.com/api/v0/sdk/{environmentId}/flow/{flowId}/source"

payload = {
    "fromAddress": "0xbF394748301603f18d953C90F0b087CBEC0E1834",
    "fromChainId": "An example name",
    "refundAddress": "0xbF394748301603f18d953C90F0b087CBEC0E1834"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fromAddress: '0xbF394748301603f18d953C90F0b087CBEC0E1834',
    fromChainId: 'An example name',
    refundAddress: '0xbF394748301603f18d953C90F0b087CBEC0E1834'
  })
};

fetch('https://app.dynamicauth.com/api/v0/sdk/{environmentId}/flow/{flowId}/source', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.dynamicauth.com/api/v0/sdk/{environmentId}/flow/{flowId}/source",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fromAddress' => '0xbF394748301603f18d953C90F0b087CBEC0E1834',
    'fromChainId' => 'An example name',
    'refundAddress' => '0xbF394748301603f18d953C90F0b087CBEC0E1834'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.dynamicauth.com/api/v0/sdk/{environmentId}/flow/{flowId}/source"

	payload := strings.NewReader("{\n  \"fromAddress\": \"0xbF394748301603f18d953C90F0b087CBEC0E1834\",\n  \"fromChainId\": \"An example name\",\n  \"refundAddress\": \"0xbF394748301603f18d953C90F0b087CBEC0E1834\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.dynamicauth.com/api/v0/sdk/{environmentId}/flow/{flowId}/source")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fromAddress\": \"0xbF394748301603f18d953C90F0b087CBEC0E1834\",\n  \"fromChainId\": \"An example name\",\n  \"refundAddress\": \"0xbF394748301603f18d953C90F0b087CBEC0E1834\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.dynamicauth.com/api/v0/sdk/{environmentId}/flow/{flowId}/source")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fromAddress\": \"0xbF394748301603f18d953C90F0b087CBEC0E1834\",\n  \"fromChainId\": \"An example name\",\n  \"refundAddress\": \"0xbF394748301603f18d953C90F0b087CBEC0E1834\"\n}"

response = http.request(request)
puts response.read_body

200

{
  "sessionExpiresAt": "2023-11-07T05:31:56Z",
  "sessionToken": "dct_A1B2C3...",
  "flow": {
    "id": "95b11417-f18f-457f-8804-68e361f9164f",
    "amount": "<string>",
    "currency": "An example name",
    "quoteVersion": 123,
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "memo": {},
    "userId": "95b11417-f18f-457f-8804-68e361f9164f",
    "fromAddress": "0xbF394748301603f18d953C90F0b087CBEC0E1834",
    "fromChainId": "An example name",
    "fromToken": "An example name",
    "toAddress": "0xbF394748301603f18d953C90F0b087CBEC0E1834",
    "toChainId": "An example name",
    "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": {
        "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>"
        }
      }
    },
    "txHash": "<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"
    },
    "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,
    "settlementConfig": {
      "settlements": [
        {
          "tokenAddress": "An example name",
          "chainId": "An example name",
          "symbol": "An example name",
          "tokenDecimals": 18,
          "isNative": true
        }
      ]
    },
    "destinationConfig": {
      "destinations": [
        {
          "type": "address",
          "identifier": "An example name"
        }
      ]
    }
  }
}

{
  "error": "<string>"
}

{
  "error": "Access Forbidden"
}

{
  "error": "Not Found",
  "code": "not_found"
}

{
  "error": "Conflict: invalid state transition"
}

{
  "error": "Resources already exists for this Object",
  "payload": {
    "email": "[e-mail]",
    "embeddedWalletName": "<string>",
    "mergeConflicts": {
      "fromUser": {
        "id": "95b11417-f18f-457f-8804-68e361f9164f",
        "projectEnvironmentId": "95b11417-f18f-457f-8804-68e361f9164f",
        "verifiedCredentials": [
          {
            "id": "95b11417-f18f-457f-8804-68e361f9164f",
            "signInEnabled": true,
            "address": "0xbF394748301603f18d953C90F0b087CBEC0E1834",
            "chain": "<string>",
            "refId": "95b11417-f18f-457f-8804-68e361f9164f",
            "signerRefId": "95b11417-f18f-457f-8804-68e361f9164f",
            "email": "[e-mail]",
            "name_service": {
              "avatar": "<string>",
              "name": "<string>"
            },
            "public_identifier": "<string>",
            "wallet_name": "<string>",
            "wallet_properties": {
              "turnkeySubOrganizationId": "95b11417-f18f-457f-8804-68e361f9164f",
              "turnkeyPrivateKeyId": "95b11417-f18f-457f-8804-68e361f9164f",
              "turnkeyHDWalletId": "95b11417-f18f-457f-8804-68e361f9164f",
              "isAuthenticatorAttached": true,
              "turnkeyUserId": "95b11417-f18f-457f-8804-68e361f9164f",
              "isSessionKeyCompatible": true
            },
            "business_account_properties": {
              "businessAccountId": "95b11417-f18f-457f-8804-68e361f9164f",
              "businessAccountCreatedAt": "2023-11-07T05:31:56Z",
              "businessAccountSignerId": "95b11417-f18f-457f-8804-68e361f9164f",
              "businessAccountName": "<string>",
              "businessAccountExternalRef": "<string>"
            },
            "oauth_username": "<string>",
            "oauth_display_name": "<string>",
            "oauth_account_id": "<string>",
            "phoneNumber": "9171113333",
            "phoneCountryCode": "1",
            "isoCountryCode": "US",
            "oauth_account_photos": [
              "<string>"
            ],
            "oauth_emails": [
              "<string>"
            ],
            "oauth_metadata": {},
            "previous_users": [
              "95b11417-f18f-457f-8804-68e361f9164f"
            ],
            "embedded_wallet_id": "<string>",
            "wallet_additional_addresses": [
              {
                "address": "<string>",
                "publicKey": "<string>",
                "network": "<string>"
              }
            ],
            "lastSelectedAt": "2023-11-07T05:31:56Z",
            "verifiedAt": "2023-11-07T05:31:56Z"
          }
        ],
        "lastVerifiedCredentialId": "95b11417-f18f-457f-8804-68e361f9164f",
        "sessionId": "95b11417-f18f-457f-8804-68e361f9164f",
        "alias": "An example name",
        "country": "US",
        "email": "[e-mail]",
        "firstName": "An example name",
        "jobTitle": "An example name",
        "lastName": "An example name",
        "phoneNumber": "<string>",
        "policiesConsent": true,
        "tShirtSize": "An example name",
        "team": "An example name",
        "username": "An example name",
        "firstVisit": "2023-11-07T05:31:56Z",
        "lastVisit": "2023-11-07T05:31:56Z",
        "newUser": true,
        "metadata": {},
        "btcWallet": "<string>",
        "kdaWallet": "<string>",
        "ltcWallet": "<string>",
        "ckbWallet": "<string>",
        "kasWallet": "<string>",
        "dogeWallet": "<string>",
        "emailNotification": true,
        "discordNotification": true,
        "newsletterNotification": true,
        "lists": [
          "<string>"
        ],
        "scope": "superuser marketing operations",
        "missingFields": [
          {
            "name": "<string>",
            "required": true,
            "enabled": true,
            "unique": true,
            "verify": true,
            "validationRules": {
              "unique": true,
              "regex": "^0x",
              "validOptions": [
                {
                  "label": "small"
                },
                {
                  "label": "medium"
                },
                {
                  "label": "large"
                }
              ],
              "checkboxText": "Agree to the terms and conditions"
            },
            "label": "<string>",
            "position": 123
          }
        ]
      },
      "conflicts": [
        {
          "field": {
            "name": "<string>",
            "required": true,
            "enabled": true,
            "unique": true,
            "verify": true,
            "validationRules": {
              "unique": true,
              "regex": "^0x",
              "validOptions": [
                {
                  "label": "small"
                },
                {
                  "label": "medium"
                },
                {
                  "label": "large"
                }
              ],
              "checkboxText": "Agree to the terms and conditions"
            },
            "label": "<string>",
            "position": 123
          },
          "fromUser": {
            "userId": "95b11417-f18f-457f-8804-68e361f9164f",
            "value": "An example name"
          },
          "currentUser": {
            "userId": "95b11417-f18f-457f-8804-68e361f9164f",
            "value": "An example name"
          }
        }
      ]
    },
    "additionalMessages": [
      "<string>"
    ]
  }
}

{
  "error": "Internal Server Error"
}

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. Required when no JWT is provided. Format: dft_.

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 and fromChainName are required; fromAddress is not accepted (use refundAddress instead to specify where funds should be returned if the deposit fails).

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

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). 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:

"dct_A1B2C3..."

flow · object · required

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

Show child attributes