Auto Convert Routes

Auto Convert Routes create reusable receiving instructions. Funds that arrive through the route are converted and forwarded to its saved destination. A route can be backed by a virtual account or a liquidation address.

Discover the route first

Call GetTransfersInfoQueryV1 and select a returned option with flowType: "AutoConvert". Use its full route object. Do not assume that a currency or rail is available because another account has it.

Set includeExistingAutoConvertRouteTargets: true when the user is editing an existing route and its current destination must remain selectable.

Create an Auto Convert Route

curl https://api-preview.bridflow.com/transfers/auto/v1   --request POST   --header 'Content-Type: application/json'   --header 'Authorization: Basic <BASE64(uuid:password)>'   --header 'AccountId: 123e4567-e89b-12d3-a456-426614174000'   --data '{
    "destinationSavedContactId": "123e4567-e89b-12d3-a456-426614174001",
    "execute": false,
    "route": {
      "routeKey": "auto-eur-sepa-to-usdc-base",
      "flowType": "AutoConvert",
      "provider": "<opaque-provider>",
      "source": {
        "currency": "Eur",
        "paymentRail": "Sepa",
        "currencyKind": "Fiat"
      },
      "destination": {
        "currency": "Usdc",
        "paymentRail": "Base",
        "currencyKind": "Crypto"
      }
    }
  }'

Use execute: false first. A current preview response has this shape:

{
	"previewKind": "AutoConvert",
	"wasCommitted": false,
	"autoConvertRouteWasCreated": false,
	"isReadyToExecute": true,
	"summary": "Ready to create Auto Convert Route",
	"nextAction": null,
	"route": {},
	"provider": "<opaque-provider>",
	"sourceInstruction": {},
	"destinationInstruction": {},
	"blockingValidationMessages": [],
	"sourceDepositInstruction": null,
	"sourceDepositTransferId": null,
	"virtualAccount": null,
	"liquidationAddress": null
}

When ready, repeat the same request with execute: true. The committed response returns either virtualAccount or liquidationAddress with the receiving details.

Avoid duplicate routes

Only one active Auto Convert Route can exist for a source route.

• Virtual-account routes are unique by source currency.
• Liquidation-address routes are unique by source currency and source payment rail.
• If discovery or creation reports an existing route, show it and offer to update its destination.

The provider is authoritative for duplicate detection. Handle its conflict response even if a local projection has not caught up yet.

List Auto Convert Routes

curl https://api-preview.bridflow.com/transfers/auto/list/v1   --request QUERY   --header 'Content-Type: application/json'   --header 'Authorization: Basic <BASE64(uuid:password)>'   --header 'AccountId: 123e4567-e89b-12d3-a456-426614174000'   --data '{
    "query": {
      "filter": [],
      "select": null,
      "sort": [],
      "pagination": {
        "page": 0,
        "pageSize": 20
      },
      "exportFormat": "Json",
      "returnPropertyInfo": true
    }
  }'

Important list fields:

• kindAutoConvertRoute: VirtualAccount or LiquidationAddress.
• providerRouteIdAutoConvertRoute: internal route id required for route commands.
• Source and destination currency, payment rail, and primary identifier fields.
• feePercentageAutoConvertRoute: configured percentage for the route.
• canDisableAutoConvertRoute, canEnableAutoConvertRoute, and canUpdateDestinationAutoConvertRoute: allowed actions.

Enable or disable a route

{
	"kind": "VirtualAccount",
	"providerRouteId": "ccf79fda-e419-4a3e-aa43-a37f7f80fb40",
	"enabled": false
}

Only offer the action when the list response says it is allowed.

Change the destination

{
	"kind": "VirtualAccount",
	"providerRouteId": "ccf79fda-e419-4a3e-aa43-a37f7f80fb40",
	"destinationSavedContactId": "123e4567-e89b-12d3-a456-426614174001",
	"execute": false,
	"route": {
		"routeKey": "auto-eur-sepa-to-usdc-base",
		"flowType": "AutoConvert",
		"provider": "<opaque-provider>",
		"source": {
			"currency": "Eur",
			"paymentRail": "Sepa",
			"currencyKind": "Fiat"
		},
		"destination": {
			"currency": "Usdc",
			"paymentRail": "Base",
			"currencyKind": "Crypto"
		}
	}
}

Preview with execute: false, then confirm with execute: true. Updating only the destination does not require the client to resend a fee percentage; the backend resolves the existing route and current account fee configuration.