Create Swap

Create a new swap based on an existing quote. This is the second step of the Swap flow.

POST /swaps

Create Swap

cURL

curl --request POST \
  --url https://api.dfns.io/swaps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-DFNS-USERACTION: <api-key>' \
  --data '
{
  "quoteId": "swapQuote-3hgv4-q8tbf-8v2ajmrbmg6m4i9t",
  "reference": "optional reference for record keeping",
  "provider": "UniswapClassic",
  "walletId": "wa-123456-12345678",
  "targetWalletId": "wa-123456-87654321",
  "slippageBps": 50,
  "sourceAsset": {
    "kind": "Native",
    "amount": "1000000000000000000"
  },
  "targetAsset": {
    "kind": "Erc20",
    "contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amount": "5600000"
  }
}
'

200

{
  "id": "swap-6a3ku-bn8d7-8u5rs1oukojms7k8",
  "quoteId": "swapQuote-3hgv4-q8tbf-8v2ajmrbmg6m4i9t",
  "reference": null,
  "walletId": "wa-3l3cj-l8mq7-8q78f9nopq7f1qjv",
  "targetWalletId": "wa-3l3cj-l8mq7-8q78f9nopq7f1qjv",
  "status": "PendingPolicyApproval",
  "provider": "UniswapClassic",
  "quotedSourceAsset": {
    "kind": "Native",
    "amount": "10000000000",
    "metadata": {
      "network": "EthereumSepolia",
      "name": "Ethereum",
      "symbol": "SepoliaETH",
      "decimals": 18,
      "tid": "native:eth"
    }
  },
  "quotedTargetAsset": {
    "kind": "Erc20",
    "contract": "0xda0be7efd234295395d4204d0df4358339b57b27",
    "amount": "6467571553831928182",
    "metadata": {
      "network": "EthereumSepolia",
      "name": "Test",
      "symbol": "Test",
      "decimals": 18,
      "tid": "erc20:0xda0be7efd234295395d4204d0df4358339b57b27"
    }
  },
  "slippageBps": 100,
  "dateCreated": "2025-09-11T10:57:55.758Z",
  "requestBody": {
    "quoteId": "swapQuote-3hgv4-q8tbf-8v2ajmrbmg6m4i9t",
    "walletId": "wa-3l3cj-l8mq7-8q78f9nopq7f1qjv",
    "targetWalletId": "wa-3l3cj-l8mq7-8q78f9nopq7f1qjv",
    "provider": "UniswapClassic",
    "slippageBps": 100,
    "sourceAsset": {
      "kind": "Native",
      "amount": "10000000000"
    },
    "targetAsset": {
      "kind": "Erc20",
      "contract": "0xda0be7efd234295395d4204d0df4358339b57b27",
      "amount": "653003161"
    }
  },
  "requester": {
    "userId": "us-48r5q-eshfg-9pmr2lo6bmpr4i4i",
    "tokenId": "to-4etah-smoal-9n3rmhul4dpaueg5"
  }
}

Authentication

✅ Organization User (CustomerEmployee)
❌ Delegated User (EndUser)
✅ Service Account

Required Permissions

Swaps:Create: Always required.

Authorizations

Authorization · string · header · required

Bearer Token: Used to authenticate API requests. More details how to generate the token: Authentication flows

X-DFNS-USERACTION · string · header · required

User Action Signature: Used to sign the change-inducing API requests. More details how to generate the token: User Action Signing flows

Body

application/json

UniswapClassic Swap Request

UniswapX Swap Request

CircleCctp Swap Request

provider · enum<string> · required

Available options: UniswapClassic

quoteId · string · required

Quote to use for this swap.

Required string length: 1 - 64

Pattern: ^swapQuote-[a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{14,16}$

Example:

"swapQuote-7n9p0-cth75-6l74n2sj7u73ooeq"

walletId · string · required

Id of the Dfns wallet spending the sourceAsset. Used for attesting that the swap is being created with the same parameters as the quote.

Required string length: 1 - 64

Pattern: ^wa-[a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{14,16}$

Example:

"wa-5pfuu-9euek-h0odgb6snva8ph3k"

sourceAsset · Native Asset · object · required

The source asset that will be spent on the Swap transaction. Used for attesting that the swap is being created with the same parameters as the quote.

Native Asset

EVM Fungible Token (ERC-20)

Solana Fungible Token (SPL)

Show child attributes

targetAsset · Native Asset · object · required

The target asset that will be received with the Swap transaction. Used for attesting that the swap is being created with the same parameters as the quote.

Native Asset

EVM Fungible Token (ERC-20)

Solana Fungible Token (SPL)

Show child attributes

slippageBps · integer · required

The slippage tolerance for this trade in basis point (BPS). Slippage tolerance defines the maximum price difference you're willing to accept during a trade from the estimated quote, ensuring you still receive at least a minimum number of tokens if the price shifts. One basis point equals one-hundredth of a percentage point, or 0.01%.

Required range: 0 <= x <= 10000

reference · string

An optional reference for this Swap.

targetWalletId · string

Id of the Dfns wallet receiving the target asset. Currently this value must be the same as the walletId. Used for attesting that the swap is being created with the same parameters as the quote.

Required string length: 1 - 64

Pattern: ^wa-[a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{14,16}$

Example:

"wa-5pfuu-9euek-h0odgb6snva8ph3k"

Response

200 - application/json

Success

id · string · required

Swap id.

Required string length: 1 - 64

Pattern: ^swap-[a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{14,16}$

Example:

"swap-5ch70-fc3n7-3k2cbo8d7q5lnts4"

quoteId · string · required

Id of the quote this swap is based on.

Required string length: 1 - 64

Pattern: ^swapQuote-[a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{14,16}$

Example:

"swapQuote-7n9p0-cth75-6l74n2sj7u73ooeq"

reference · string | null · required

Optional user-defined reference for this Swap.

walletId · string · required

Id of the Dfns wallet spending the sourceAsset.

Required string length: 1 - 64

Pattern: ^wa-[a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{14,16}$

Example:

"wa-5pfuu-9euek-h0odgb6snva8ph3k"

targetWalletId · string · required

Id of the Dfns wallet receiving the target asset. Currently this value must be the same as the walletId.

Required string length: 1 - 64

Pattern: ^wa-[a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{14,16}$

Example:

"wa-5pfuu-9euek-h0odgb6snva8ph3k"

status · enum<string> · required

Swap status.

Available options: PendingPolicyApproval, InProgress, Completed, Failed, Rejected

provider · enum<string> · required

Swap provider.

Available options: UniswapX, UniswapClassic, CircleCctp

quotedSourceAsset · Native Asset · object · required

The source asset for this swap transaction.

Native Asset

EVM Fungible Token (ERC-20)

Solana Fungible Token (SPL)

Show child attributes

quotedTargetAsset · Native Asset · object · required

The target asset for this swap transaction.

Native Asset

EVM Fungible Token (ERC-20)

Solana Fungible Token (SPL)

Show child attributes

slippageBps · number · required

The slippage tolerance for this trade in basis point (BPS). Slippage tolerance defines the maximum price difference you are willing to accept during a trade from the estimated quote, ensuring you still receive at least a minimum number of tokens if the price shifts. One basis point equals one-hundredth of a percentage point, or 0.01%.

dateCreated · string<date-time> · required

ISO 8601 date (must be UTC). When the swap was initiated.

requestBody · UniswapClassic Swap Request · object · required

The full request used for initiating this swap.

UniswapClassic Swap Request

UniswapX Swap Request

CircleCctp Swap Request

Option 4

Show child attributes

requester · object · required

The user who initiated the request.

Show child attributes

failureReason · string

The failure reason, if any. Only present when status is Failed.

protocolStatus · string

Provider-specific intermediate state, only set while status is InProgress. Values are opaque strings — clients map them to progress bars, labels or icons as needed. For CCTP one of: signing-permit, burning-source, awaiting-source-finality, awaiting-attestation, awaiting-forwarder. Undefined for providers without intermediate sub-states.