Auto Convert Routes

Auto Convert Routes let an account receive funds through an open route and automatically settle them to a selected destination. They replace the legacy virtual account setup flow and also support liquidation address routes.

The legacy /virtual-accounts/v1 endpoint remains in the API for compatibility, but new integrations should use Auto Convert Routes.

When to use Auto Convert Routes

Use Auto Convert Routes when the user does not know the amount yet.
Use them when future incoming funds should automatically settle to a selected wallet or bank account.
Do not create duplicates. If a matching source route already exists, update its destination instead.

Create an Auto Convert Route

Create a route from a flowType: "AutoForwarding" route returned by GetTransfersInfoQueryV1. The destination must be a saved contact compatible with the route destination.

POST /transfers/auto/v1 CreateAutoConvertRouteV1

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

Set execute to false to dry-run validation and preview instructions without creating the route. Set it to true after the user confirms.

Expected dry-run response shape:

{
  "autoConvertRouteWasCreated": false,
  "isReadyToExecute": true,
  "summary": "Ready to create Auto Convert Route",
  "sourceInstruction": {
    "instruction": {
      "currency": "Eur",
      "paymentRail": "Sepa"
    }
  },
  "destinationInstruction": {
    "instruction": {
      "currency": "Usdc",
      "paymentRail": "Base",
      "primaryIdentifier": "0x123456789abcdef0123456789abcdef01234567"
    }
  },
  "blockingValidationMessages": []
}

Route uniqueness

Only one active Auto Convert Route can exist for the same source route. For virtual-account style routes, uniqueness is based on source currency. For liquidation address routes, uniqueness is based on source currency and source payment rail.

If the route already exists, update its destination instead of creating a duplicate.

List Auto Convert Routes

QUERY /transfers/auto/list/v1 GetAutoConvertRouteListQueryV1

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

Important fields returned by the list:

kindAutoConvertRoute: VirtualAccount or LiquidationAddress.
providerRouteIdAutoConvertRoute: route id required for enable, disable, and destination updates. Keep this internal.
sourceCurrencyAutoConvertRoute and sourcePaymentRailAutoConvertRoute: route source.
destinationCurrencyAutoConvertRoute, destinationPaymentRailAutoConvertRoute, and destinationPrimaryIdentifierAutoConvertRoute: current destination.
feePercentageAutoConvertRoute: route fee percentage.
canDisableAutoConvertRoute, canEnableAutoConvertRoute, canUpdateDestinationAutoConvertRoute: supported actions.

Route states

Status	Meaning	User-facing handling
`activated`	Route can receive funds.	Show as active.
`deactivated`	Route cannot currently receive funds.	Show as disabled and allow enable when `canEnableAutoConvertRoute` is true.
`pending`	Route is being created or updated.	Show as pending and refresh later.
`failed`	Route could not be created or updated.	Show error details and allow retry when appropriate.

Enable or disable a route

Use the status endpoint for routes whose list response shows canDisableAutoConvertRoute or canEnableAutoConvertRoute.

POST /transfers/auto/disable/v1 DisableAutoConvertRouteCommandV1

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

Set enabled to true to enable a disabled route.

Expected response:

{
  "autoConvertRouteStatusWasUpdated": true,
  "autoConvertRouteWasDisabled": true,
  "autoConvertRouteWasEnabled": false,
  "kind": "VirtualAccount",
  "providerRouteId": "ccf79fda-e419-4a3e-aa43-a37f7f80fb40",
  "message": "Route status was updated."
}

Change route destination

Use this endpoint when a source route already exists and the user wants to send future funds to a different saved contact.

POST /transfers/auto/update-destination/v1 UpdateAutoConvertRouteDestinationCommandV1

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

The route object must still match the existing source route and the new destination saved contact.