Transfers

Use transfer route discovery before creating Direct Transfers or Auto Convert Routes. The route objects returned by GetTransfersInfoQueryV1 are the supported transfer paths; clients should not hardcode source and destination pairs.

Only create transfers or Auto Convert Routes from routes returned by GetTransfersInfoQueryV1. Unsupported route objects are rejected by the API.

Route selection flow

Call GetTransfersInfoQueryV1 with no selection to get all available sources and destinations.
When the user selects a source, call it again with selectedSource.
When the user selects a destination, call it again with both selected sides.
Pick one returned routes[] item and use its route object in the create command.
Treat provider, route key, and plan fields as opaque routing metadata. Echo them from discovery; do not construct them or show provider names to users.

Discover available routes

QUERY /transfers/info/v1 GetTransfersInfoQueryV1

curl https://api-preview.kunga.eu/transfers/info/v1   --request QUERY   --header 'Content-Type: application/json'   --header 'Authorization: Basic <BASE64(uuid:password)>'   --data '{
    "selectedSource": null,
    "selectedDestination": null
  }'

Example route option:

{
  "routeKey": "auto-eur-sepa-to-usdc-base",
  "flowType": "AutoForwarding",
  "route": {
    "routeKey": "auto-eur-sepa-to-usdc-base",
    "flowType": "AutoForwarding",
    "provider": "<opaque-provider>",
    "source": {
      "currency": "Eur",
      "paymentRail": "Sepa",
      "currencyKind": "Fiat"
    },
    "destination": {
      "currency": "Usdc",
      "paymentRail": "Base",
      "currencyKind": "Crypto"
    }
  },
  "totalPercentageFee": 0.015,
  "minimumSourceAmount": 1
}

The response includes:

availableSources: source assets and rails supported for the current selection.
availableDestinations: destination assets and rails supported for the current selection.
routes: executable route options with flow type, source, destination, fulfillment metadata, and fee estimates.
totalPercentageFee, totalSourceBaseFee, and minimumSourceAmount: route cost and minimum amount metadata.

Common route patterns

User goal	Expected flow type	Typical next step
Send a specific amount now	`Direct`	Create or select source and destination saved contacts, then create a Direct Transfer.
Receive future bank funds and auto-settle	`AutoForwarding`	Create an Auto Convert Route.
Change where future funds settle	`AutoForwarding`	List Auto Convert Routes and update the existing route destination.
Review historical movement	Any transfer kind	Query `/transfers/list/v1` or transfer details.

Get route-specific fields

After a route is selected, call the metadata endpoint to determine which fields are required for source and destination instructions.

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

curl https://api-preview.kunga.eu/transfers/route-field-metadata/v1   --request QUERY   --header 'Content-Type: application/json'   --header 'Authorization: Basic <BASE64(uuid:password)>'   --data '{
    "route": {
      "flowType": "Direct",
      "provider": "<route.provider>",
      "source": {
        "currency": "Eur",
        "paymentRail": "Sepa",
        "currencyKind": "Fiat"
      },
      "destination": {
        "currency": "Usdc",
        "paymentRail": "Base",
        "currencyKind": "Crypto"
      }
    }
  }'

Example metadata response:

{
  "sourceFields": [
    {
      "type": "Iban",
      "identifier": "PrimaryIdentifier",
      "required": true,
      "label": "IBAN",
      "placeholder": "Enter IBAN"
    }
  ],
  "destinationFields": [
    {
      "type": "WalletAddress",
      "identifier": "PrimaryIdentifier",
      "required": true,
      "label": "Base wallet address",
      "placeholder": "Enter wallet address"
    }
  ]
}

Use returned labels, placeholders, options, and required flags to build the payment instruction or saved contact form.

Create a Direct Transfer

Create direct transfers with CreateDirectTransferCommandV1 after selecting a Direct route and collecting the required source and destination contacts.

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": "<route.provider>",
    "source": {
      "currency": "Eur",
      "paymentRail": "Sepa",
      "currencyKind": "Fiat"
    },
    "destination": {
      "currency": "Usdc",
      "paymentRail": "Base",
      "currencyKind": "Crypto"
    }
  }
}

Set execute to false to validate the transfer and preview the review object. Set it to true when the user confirms.

Expected response shape:

{
  "status": {
    "transferWasExecuted": false,
    "isReadyToExecute": true,
    "summary": "Ready to create transfer",
    "blockingValidationMessages": []
  },
  "review": {
    "sourceAmount": 100,
    "route": {}
  },
  "execution": {}
}

List transfers

QUERY /transfers/list/v1 GetTransferListQueryV1

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

The list can include direct transfers, auto-conversions, refunds, and conversion records. User-facing screens should explain the transfer kind before showing source and destination details.

Transfer kinds

Kind	Meaning
`DirectTransfer`	User-created transfer for a specific amount.
`AutoConversion`	Funds arrived through an Auto Convert Route and were automatically settled.
`Refund`	Funds were returned or refunded.

Transfer lifecycle

Status	Meaning	User-facing handling
`Created`	Transfer was created but has not progressed yet.	Show as created or waiting.
`ActionRequired`	The user or integrator must complete a required action.	Show the required action.
`Pending`	Transfer is being processed.	Show as in progress.
`InReview`	Transfer is under review.	Show as in review and avoid duplicate submissions.
`Completed`	Transfer completed successfully.	Show final amounts and receipts when available.
`Canceled`	Transfer was canceled.	Show as canceled.
`Failed`	Transfer failed.	Show the failure reason when available.
`Refunded`	Transfer was refunded.	Show refund details.
`Returning`	Transfer is being returned.	Show as returning.
`AmountTooSmall`	Transfer amount is below the minimum route amount.	Ask the user to enter a larger amount.