Quick Start

This guide shows the shortest complete server-to-server integration path. Use it to verify credentials, onboard an account, discover supported routes, and create either a Direct Transfer or an Auto Convert Route.

Do not hardcode transfer paths. Always start from GetTransfersInfoQueryV1 and use one of the returned route objects.

1. Verify authentication

QUERY /identity/current/v1 GetCurrentIdentityUserQueryV1
curl -u "uuid:password"   https://api-preview.kunga.eu/identity/current/v1   --request QUERY   --header 'Content-Type: application/json'   --data '{}'

Expected result: the response identifies the authenticated External API Consumer or user context.

2. Create an account

POST /accounts/full/v1 CreateFullAccountCommandV1
curl https://api-preview.kunga.eu/accounts/full/v1   --request POST   --header 'Content-Type: application/json'   --header 'Authorization: Basic <BASE64(uuid:password)>'   --data '{
    "accountType": "Personal",
    "email": "[email protected]",
    "birthDate": "1990-01-15",
    "name": "Alex",
    "lastName": "Rivera",
    "identificationType": "Passport",
    "identificationNumber": "X1234567",
    "phoneNumber": "+34600000000",
    "address": {
      "streetLine1": "Example Street 10",
      "city": "Madrid",
      "stateName": "Madrid",
      "stateCode": "MD",
      "countryName": "Spain",
      "countryCode": "ESP",
      "postalCode": "28001"
    }
  }'

Expected result:

{
  "personId": "123e4567-e89b-12d3-a456-426614174000",
  "companyId": null
}

3. Poll account status

QUERY /accounts/status/v1 GetAccountStatusQueryV1
curl https://api-preview.kunga.eu/accounts/status/v1   --request QUERY   --header 'Content-Type: application/json'   --header 'Authorization: Basic <BASE64(uuid:password)>'   --data '{}'

Continue polling after each required user action until accountCreationStatus is Complete.

4. Discover 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
  }'

The response returns availableSources, availableDestinations, and routes. Pick a route from routes and echo that route object into the next transfer command. Treat provider fields in route objects as opaque routing metadata.

Choosing the next action

  • Use flowType: "Direct" when the user wants to send a specific amount now.
  • Use flowType: "AutoForwarding" when the user wants an open route that automatically converts funds when they arrive.
  • Use route metadata before collecting account or wallet fields from the user.

5. Get required fields

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"
      }
    }
  }'

Expected result: sourceFields and destinationFields describe the labels, field types, required flags, and validation rules to show in your form.

6. Save a reusable destination

POST /saved-contacts/v1 UpsertSavedContactCommandV1
{
  "isSavedByUser": true,
  "alias": "Treasury USDC wallet",
  "instruction": {
    "kind": "External",
    "currency": "Usdc",
    "paymentRail": "Base",
    "primaryIdentifier": "0x123456789abcdef0123456789abcdef01234567"
  }
}

Use the returned saved contact id when creating Auto Convert Routes or transfer destinations that require a saved contact.

7. Create the route or transfer

Auto Convert Route

Create this when funds should arrive later through an open route and automatically settle to the saved destination.

POST /transfers/auto/v1 with CreateAutoConvertRouteV1

Direct Transfer

Create this when the user is sending a specific amount now.

POST /transfers/direct/v1 with CreateDirectTransferCommandV1

Use the execute flag when supported by the command to validate and preview before creating the real resource.