Transfers

Use route discovery before creating a Direct Transfer or Auto Convert Route. The route table returned by GetTransfersInfoQueryV1 is the source of truth for supported currencies, payment rails, providers, minimums, and fees.

Do not build a route from assumptions or an old provider capability list. Only submit a complete route object returned for the current account and current selection.

Route selection flow

Call GetTransfersInfoQueryV1 with no source or destination.
Call it again after either side changes.
Render only the returned availableSources and availableDestinations.
Select one returned routes[] item and keep its full route object.
Treat provider, route key, fulfillment, and plan fields as opaque data.

Discover available routes

QUERY /transfers/info/v1 GetTransfersInfoQueryV1

curl https://api-preview.bridflow.com/transfers/info/v1   --request QUERY   --header 'Content-Type: application/json'   --header 'Authorization: Basic <BASE64(uuid:password)>'   --header 'AccountId: 123e4567-e89b-12d3-a456-426614174000'   --data '{
    "selectedSource": null,
    "selectedDestination": null,
    "includeExistingAutoConvertRouteTargets": false
  }'

Example route option:

{
	"routeKey": "auto-eur-sepa-to-usdc-base",
	"sortPriority": 10,
	"isPreferred": true,
	"provider": "<opaque-provider>",
	"flowType": "AutoConvert",
	"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"
		}
	},
	"totalPercentageFee": 1.45,
	"totalSourceBaseFee": 1.0,
	"minimumSourceAmount": 1.0,
	"existingAutoConvertRouteTarget": null
}

The response includes:

availableSources and availableDestinations: choices valid for the current selection.
routes: executable options with flow type, route, fulfillment data, and plan.
totalPercentageFee: total percentage shown to the account for this route.
totalSourceBaseFee: fixed source fee, when the route supports one.
minimumSourceAmount: smallest valid source amount.
existingAutoConvertRouteTarget: an existing route that should be updated instead of duplicated.

Flow types

User goal	Flow type	Next action
Send a known amount now	`Direct`	Preview and create a Direct Transfer.
Receive future funds and settle them automatically	`AutoConvert`	Preview and create an Auto Convert Route.
Change the destination of an existing open route	`AutoConvert`	Update the route destination.

Get route-specific fields

QUERY /transfers/route-field-metadata/v1 GetTransferRouteFieldMetadataQueryV1

Send the exact route selected in discovery:

{
	"route": {
		"routeKey": "direct-eur-sepa-to-usdc-base",
		"flowType": "Direct",
		"provider": "<opaque-provider>",
		"source": {
			"currency": "Eur",
			"paymentRail": "Sepa",
			"currencyKind": "Fiat"
		},
		"destination": {
			"currency": "Usdc",
			"paymentRail": "Base",
			"currencyKind": "Crypto"
		}
	}
}

The response contains sourceFields, destinationFields, sourceWarnings, destinationWarnings, and flowType.

Build forms from metadata

Use the returned identifier, label, type, options, required flag, and validation rules.
Apply conditional fields using visibleWhenIdentifier and visibleWhenValue.
Display relevant route warnings before confirmation.
Include Memo or Reference only when metadata returns it. Do not request a memo for Ethereum, Base, or another rail that does not support one.

Create a Direct Transfer

POST /transfers/direct/v1 CreateDirectTransferCommandV1

{
	"sourceAmount": 100,
	"sourceSavedContactId": "123e4567-e89b-12d3-a456-426614174000",
	"destinationSavedContactId": "123e4567-e89b-12d3-a456-426614174001",
	"execute": false,
	"route": {
		"routeKey": "direct-eur-sepa-to-usdc-base",
		"flowType": "Direct",
		"provider": "<opaque-provider>",
		"source": {
			"currency": "Eur",
			"paymentRail": "Sepa",
			"currencyKind": "Fiat"
		},
		"destination": {
			"currency": "Usdc",
			"paymentRail": "Base",
			"currencyKind": "Crypto"
		}
	}
}

Use execute: false first. The response includes:

isReadyToExecute and blockingValidationMessages: whether confirmation is allowed.
quote: source and destination amounts before and after fees, fixed fees, percentage fees, and total fees.
sourceInstruction and destinationInstruction: resolved instruction summaries.
sourceDepositInstruction: deposit details when the transfer needs incoming funds first.
status, review, and execution: preview and execution state.
wasCommitted: whether the request created the real transfer.

Show the quote to the user, then repeat the same command with execute: true. Keep the route and saved contacts unchanged between preview and execution unless you request a fresh preview.

Direct Transfer quotes can include both a percentage fee and a fixed base fee. Never display a fixed fee of zero because a client-side table does not know the cost. Use the discovery option and preview quote returned by the API.

List transfers

QUERY /transfers/list/v1 GetTransferListQueryV1

curl https://api-preview.bridflow.com/transfers/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": [],
      "sort": [],
      "pagination": {
        "page": 0,
        "pageSize": 20
      },
      "exportFormat": "Json"
    }
  }'

The list combines provider events that belong to one transfer into one user-facing movement with a timeline. It can include direct transfers, automatic conversions, refunds, returns, and provider review states.

Safe handling

Do not create a duplicate transfer while a previous request has an unknown outcome.
Do not retry an under_review operation as a new transfer.
Refresh discovery after an unsupported-route response.
Keep the exact route and idempotency context when retrying a timeout.
Use the returned failure or return reason instead of a generic minimum-amount message.