User

This module contains endpoints for creating and managing users.
The standard flow for user - create user → add kyc-files → add user document verification

---

Create user account and genereate all balances

Each user must have unique externalUserId. If user with this externalUserId already exists, error will be thrown. Fiat balances is created asynchronously, when created it gets the status 'WAITING_TO_BE_ACTIVATED', when it is created correctly we will send information about it using a webhook /webhook/user/status

Method: POST
Endpoint: /v1/user/balances/crypto-and-fiat

Request

Request body - required

Name	Type	Required	Description
externalUserId	string	Yes	External user id (from your system)
email	string	Yes	Email
phone	string	Yes	Phone
firstName	string	Yes	First name
lastName	string	Yes	Last name
birthDate	date	Yes	Birth date
birthCountry	string	No	ISO 3166-1 alpha-2 country code
pesel	string	No	Pesel
address	string	Yes	Address
city	string	Yes	City
postCode	string	Yes	Post code
country	string	Yes	ISO 3166-1 alpha-2 country code
documentType	string	Yes	Enum: [ "PASSPORT", "ID_CARD", "RESIDENCE_PERMIT" ]
documentNumber	string	Yes	Document number

 

Example body request

{
  "externalUserId": "bca65c48-df49-4831-a7b2-de7903321581",
  "email": "johndoe@gmail.com",
  "phone": "48123123123",
  "firstName": "John",
  "lastName": "Doe",
  "birthDate": "2000-01-01",
  "birthCountry": "PL",
  "pesel": "12345678901",
  "address": "Adama Matuszczaka 51/4",
  "city": "Rzeszów",
  "postCode": "35-083",
  "country": "PL",
  "documentType": "ID_CARD",
  "documentNumber": "CEV124630"
}

Response

Code: 200
Description: Returns our user id and all user balances

 

Response body explanation

{
  "userId": "User id (from our system)",
  "fiatBalances": [
    {
      "id": "Balance id (from our system)",
      "amount": "Amount",
      "name": "Currency name",
      "rate": "Rate",
      "iban": "IBAN number",
      "status": "Enum: [ 'ACTIVE, 'WAITING_TO_BE_ACTIVATED' ]"
    }
  ],
  "cryptoBalances": [
    {
      "id": "Balance id (from our system)",
      "amount": "Amount",
      "name": "Currency name",
      "wallet": "Wallet address",
      "rate": "Rate",
      "networkConfig": {
        [networkName]: {
          "mainnet": "Is mainnet network",
          "name": "Network name",
          "withdrawal": {
            "feeWithdrawal": "Withdrawal fee",
            "minWithdrawal": "Withdrawal min amount"
          },
          "deposit": {
            "minDeposit": "Deposit min amount"
          },
        }
      }
    }
  ]
}

 

Example response

{
  "userId": "617c6277-41cc-45ab-b2c1-b4187d823827",
  "fiatBalances": [
    {
      "id": "02ee1b09-9934-4dcc-8dec-91bf34b8f543",
      "amount": "0.00",
      "name": "eur",
      "rate": 1,
      "iban": "LT683130019950000568",
      "status": "ACTIVE"
    }
  ],
  "cryptoBalances": [
    {
      "id": "f2de1f4b-916f-417e-9410-8bf4a70693ee",
      "amount": "0.000000",
      "name": "usdc",
      "wallet": "0x2e90ca5bbe46d5ae23f2df90457d020391b92673",
      "rate": 0.963728,
      "networkConfig": {
        "ethereum": {
          "mainnet": false,
          "name": "sepolia",
          "withdrawal": {
            "feeWithdrawal": 10,
            "minWithdrawal": 15
          },
          "deposit": {
            "minDeposit": 5
          }
        },
        "polygon": {
          "mainnet": false,
          "name": "amoy",
          "withdrawal": {
            "feeWithdrawal": 10,
            "minWithdrawal": 15
          },
          "deposit": {
            "minDeposit": 5
          }
        }
      }
    },
    {
      "id": "7415034b-3dcf-4f45-a213-ce6361c248aa",
      "amount": "0.000000",
      "name": "usdt",
      "wallet": "0x2e90ca5bbe46d5ae23f2df90457d020391b92673",
      "rate": 0.963486,
      "networkConfig": {
        "ethereum": {
          "mainnet": false,
          "name": "sepolia",
          "withdrawal": {
            "feeWithdrawal": 10,
            "minWithdrawal": 15
          },
          "deposit": {
            "minDeposit": 5
          }
        },
        "polygon": {
          "mainnet": false,
          "name": "amoy",
          "withdrawal": {
            "feeWithdrawal": 10,
            "minWithdrawal": 15
          },
          "deposit": {
            "minDeposit": 5
          }
        }
      }
    },
    {
      "id": "ca5f1989-978b-422c-b0bd-b799c5e32fe8",
      "amount": "0.00000000",
      "name": "ltc",
      "wallet": "tltc1qvf4kplcdjzskhukeg58lnde4gxhqv822fpxm2t",
      "rate": 128.12666666,
      "networkConfig": {
        "btc": {
          "mainnet": false,
          "name": "test",
          "withdrawal": {
            "feeWithdrawal": 0.002,
            "minWithdrawal": 0.004
          },
          "deposit": {
            "minDeposit": 0
          }
        }
      }
    },
    {
      "id": "b28d71d3-60ae-49ac-9346-26bf5358e198",
      "amount": "0.00000000",
      "name": "pol",
      "wallet": "0x2e90ca5bbe46d5ae23f2df90457d020391b92673",
      "rate": 0.39908402,
      "networkConfig": {
        "polygon": {
          "mainnet": false,
          "name": "amoy",
          "withdrawal": {
            "feeWithdrawal": 0.001,
            "minWithdrawal": 0.00005
          },
          "deposit": {
            "minDeposit": 0
          }
        }
      }
    },
    {
      "id": "d83263ca-3e1f-4190-8739-e99900758ed2",
      "amount": "0.00000000",
      "name": "eth",
      "wallet": "0x2e90ca5bbe46d5ae23f2df90457d020391b92673",
      "rate": 3169.4854887,
      "networkConfig": {
        "ethereum": {
          "mainnet": false,
          "name": "sepolia",
          "withdrawal": {
            "feeWithdrawal": 0.003,
            "minWithdrawal": 0.006
          },
          "deposit": {
            "minDeposit": 0
          }
        }
      }
    },
    {
      "id": "fae1baed-815b-4b5f-998b-d3b2c36145da",
      "amount": "0.00000000",
      "name": "btc",
      "wallet": "tb1qsclk8wvk7zplp6t8f0954qddctqtvcrhea5gca",
      "rate": 100686.13333333,
      "networkConfig": {
        "btc": {
          "mainnet": false,
          "name": "test",
          "withdrawal": {
            "feeWithdrawal": 0.0003,
            "minWithdrawal": 0.0003
          },
          "deposit": {
            "minDeposit": 0
          }
        }
      }
    }
  ]
}

 

Code: 400
Description: User exist

Example response

{
  "errorCode": "P411",
  "errorName": "user-exists"
}

 

Code: 400
Description: User of this country cannot have iban

Example response

{
  "errorCode": "P431",
  "errorName": "forbidden-country"
}

---

Add KYC file

Method: POST
Endpoint: /v1/user/kyc-files/:externalUserId

Request

Parameters - required

Name	Type	Required	Example	Description
externalUserId	string	Yes	f9b430dc-7e1a-42a0-bbb4-9003935ea9f9	External user id (from your system)

Request body - required

Name	Type	Required	Description
front_id	file	Yes	Front photo of document passed in request. Allowed types: 'image/jpeg', 'image/png', 'image/jpg'
back_id	file	No	Back photo of document passed in request. Required only if documentType is ID_CARD. Allowed types: 'image/jpeg', 'image/png', 'image/jpg'
selfie	file	Yes	Customer face photo. Allowed types: 'image/jpeg', 'image/png', 'image/jpg'

Response

Code: 200
Description: KYC files added

Example response

{
  "message": "KYC files uploaded successfully"
}

 

Code: 400
Description: Invalid file type

Example response

{
  "errorCode": "P426",
  "errorName": "invalid-file-type"
}

---

Add user document verification

For all created users it is required to add documents for verification

Method: POST
Endpoint: /v1/user/verification

Request

Request body - required

Name	Type	Required	Description
externalUserId	string	Yes	External user id (from your system)
email	string	Yes	Email
phone	string	Yes	Phone
firstName	string	Yes	First name
lastName	string	Yes	Last name
birthDate	string	Yes	Birth date
city	string	Yes	City
street	string	Yes	Street
number	string	Yes	House number
postCode	string	Yes	Post code
country	string	Yes	ISO 3166-1 alpha-2 country code
nationality	string	Yes	ISO 3166-1 alpha-2 country code
citizenship	string	No	ISO 3166-1 alpha-2 country code
documentExpirationDate	string	Yes	Document expiration date
documentNumber	string	Yes	Document number
documentType	string	Yes	Enum: [ 'PASSPORT', 'ID_CARD', 'RESIDENCE_PERMIT' ]
incomeSource	string	Yes	Enum: [ 'BUSINESS_ACTIVITY', 'SALARY', 'OTHER', 'MAINTAINED_BY_FAMILY', 'INVESTMENTS', 'SOCIAL_BENEFITS', 'TENANCY' ]
taxId	string	No	Client's tax residency list. Required only if incomeSource is BUSINESS_ACTIVITY
additionalInfo	string	No	Aditional info to income source. Required only if incomeSource is SALARY, OTHER, MAINTAINED_BY_FAMILY, INVESTMENTS, SOCIAL_BENEFITS, TENANCY.
occupation	string	Yes	Enum: [ 'IT', 'HEALTHCARE_AND_MEDICAL_SERVICES', 'FINANCE_AND_ACCOUNTING', 'EDUCATION_AND_TEACHING', 'SALES_AND_MARKETING', 'ENGINEERING', 'CUSTOMER_SERVICE', 'ADMINISTRATION_AND_OFFICE_MANAGEMENT', 'LEGAL_SERVICES', 'ARTS_AND_DESIGN', 'RETAIL_AND_SALES', 'CONSTRUCTION_AND_TRADES', 'HUMAN_RESOURCES', 'MANUFACTURING_AND_PRODUCTION', 'SCIENCE_AND_RESEARCH' ]
riskLvl	string	Yes	Enum: [ 'LOW', 'MEDIUM', 'HIGH' ]

Example body request

{
  "externalUserId": "bca65c48-df49-4831-a7b2-de7903321581",
  "email": "johndoe@gmail.com",
  "phone": "48123123123",
  "firstName": "John",
  "lastName": "Doe",
  "birthDate": "2000-01-01",
  "city": "Rzeszów",
  "street": "Adama Matuszczaka",
  "number": "14/2",
  "postCode": "12-123",
  "country": "PL",
  "nationality": "PL",
  "citizenship": "PL",
  "documentExpirationDate": "2030-01-01",
  "documentNumber": "ABC12345",
  "documentType": "ID_CARD",
  "incomeSource": "SALARY",
  "additionalInfo": "I am a programmer",
  "occupation": "IT",
  "riskLvl": "LOW"
}

Response

Code: 200
Description: User document verification added

Example response

{
  "message": "Verification documents to user added successfully"
}

 

Code: 400
Description: User has maximum number of verifications

Example response

{
  "errorCode": "P430",
  "errorName": "maximum-number-of-verifications"
}

 

Code: 400
Description: User does not exist

Example response

{
  "errorCode": "P412",
  "errorName": "invalid-user"
}

 

Code: 404
Description: Kyc file not found

Example response

{
  "errorCode": "P427",
  "errorName": "kyc-file-not-found"
}

---

Update existing user

Method: PATCH
Endpoint: /v1/user/:externalUserId

Include only fields you want to update

Request

Parameters - required

Name	Type	Required	Example	Description
externalUserId	string	Yes	f9b430dc-7e1a-42a0-bbb4-9003935ea9f9	External user id (from your system)

Response

Code: 204
Description: User details updated

Example response

{
  "message": "User updated successfully"
}

 

Code: 400
Description: User does not exist

Example response

{
  "errorCode": "P412",
  "errorName": "invalid-user"
}

---

Delete user

Method: DELETE
Endpoint: /v1/user/:externalUserId

Deletes user, but does not delete balances

Request

Parameters - required

Name	Type	Required	Example	Description
externalUserId	string	Yes	f9b430dc-7e1a-42a0-bbb4-9003935ea9f9	External user id (from your system)

Response

Code: 204
Description: User deleted

Example response

{
  "message": "User deleted successfully"
}

 

Code: 400
Description: User does not exist

Example response

{
  "errorCode": "P412",
  "errorName": "invalid-user"
}

 

Code: 400
Description: User has balance greater than 5 EUR.

Example response

{
  "errorCode": "P429",
  "errorName": "user-balance-exceeds-limit-exception"
}

Example response

{
  "errorCode": "P429",
  "errorMessage": "User has balance greater than 5 EUR.",
  "errorName": "user-balance-exceeds-limit-exception"
}

---

Get user balance

Method: GET
Endpoint: /v1/user/:externalUserId/balances

Request

Parameters - required

Name	Type	Required	Example	Description
externalUserId	string	Yes	f9b430dc-7e1a-42a0-bbb4-9003935ea9f9	External user id (from your system)

Response

Code: 200
Description: Returns all user balances

 

Response body explanation

{
  "fiatBalances": [
    {
      "id": "Balance id (from our system)",
      "amount": "Amount",
      "name": "Currency name",
      "rate": "Rate",
      "iban": "IBAN number",
      "status": "Enum: [ 'ACTIVE, 'WAITING_TO_BE_ACTIVATED' ]"
    }
  ],
  "cryptoBalances": [
    {
      "id": "Balance id (from our system)",
      "amount": "Amount",
      "name": "Currency name",
      "wallet": "Wallet address",
      "rate": "Rate",
      "networkConfig": {
        [networkName]: {
          "mainnet": "Is mainnet network",
          "name": "Network name",
          "withdrawal": {
            "feeWithdrawal": "Withdrawal fee",
            "minWithdrawal": "Withdrawal min amount"
          },
          "deposit": {
            "minDeposit": "Deposit min amount"
          },
        }
      }
    }
  ]
}

 

Example response

{
  "fiatBalances": [
    {
      "id": "02ee1b09-9934-4dcc-8dec-91bf34b8f543",
      "amount": "0.00",
      "name": "eur",
      "rate": 1,
      "iban": "LT683130019950000568",
      "status": "ACTIVE"
    }
  ],
  "cryptoBalances": [
    {
      "id": "f2de1f4b-916f-417e-9410-8bf4a70693ee",
      "amount": "0.000000",
      "name": "usdc",
      "wallet": "0x2e90ca5bbe46d5ae23f2df90457d020391b92673",
      "rate": 0.963728,
      "networkConfig": {
        "ethereum": {
          "mainnet": false,
          "name": "sepolia",
          "withdrawal": {
            "feeWithdrawal": 10,
            "minWithdrawal": 15
          },
          "deposit": {
            "minDeposit": 5
          }
        },
        "polygon": {
          "mainnet": false,
          "name": "amoy",
          "withdrawal": {
            "feeWithdrawal": 10,
            "minWithdrawal": 15
          },
          "deposit": {
            "minDeposit": 5
          }
        }
      }
    },
    {
      "id": "7415034b-3dcf-4f45-a213-ce6361c248aa",
      "amount": "0.000000",
      "name": "usdt",
      "wallet": "0x2e90ca5bbe46d5ae23f2df90457d020391b92673",
      "rate": 0.963486,
      "networkConfig": {
        "ethereum": {
          "mainnet": false,
          "name": "sepolia",
          "withdrawal": {
            "feeWithdrawal": 10,
            "minWithdrawal": 15
          },
          "deposit": {
            "minDeposit": 5
          }
        },
        "polygon": {
          "mainnet": false,
          "name": "amoy",
          "withdrawal": {
            "feeWithdrawal": 10,
            "minWithdrawal": 15
          },
          "deposit": {
            "minDeposit": 5
          }
        }
      }
    },
    {
      "id": "ca5f1989-978b-422c-b0bd-b799c5e32fe8",
      "amount": "0.00000000",
      "name": "ltc",
      "wallet": "tltc1qvf4kplcdjzskhukeg58lnde4gxhqv822fpxm2t",
      "rate": 128.12666666,
      "networkConfig": {
        "btc": {
          "mainnet": false,
          "name": "test",
          "withdrawal": {
            "feeWithdrawal": 0.002,
            "minWithdrawal": 0.004
          },
          "deposit": {
            "minDeposit": 0
          }
        }
      }
    },
    {
      "id": "b28d71d3-60ae-49ac-9346-26bf5358e198",
      "amount": "0.00000000",
      "name": "pol",
      "wallet": "0x2e90ca5bbe46d5ae23f2df90457d020391b92673",
      "rate": 0.39908402,
      "networkConfig": {
        "polygon": {
          "mainnet": false,
          "name": "amoy",
          "withdrawal": {
            "feeWithdrawal": 0.001,
            "minWithdrawal": 0.00005
          },
          "deposit": {
            "minDeposit": 0
          }
        }
      }
    },
    {
      "id": "d83263ca-3e1f-4190-8739-e99900758ed2",
      "amount": "0.00000000",
      "name": "eth",
      "wallet": "0x2e90ca5bbe46d5ae23f2df90457d020391b92673",
      "rate": 3169.4854887,
      "networkConfig": {
        "ethereum": {
          "mainnet": false,
          "name": "sepolia",
          "withdrawal": {
            "feeWithdrawal": 0.003,
            "minWithdrawal": 0.006
          },
          "deposit": {
            "minDeposit": 0
          }
        }
      }
    },
    {
      "id": "fae1baed-815b-4b5f-998b-d3b2c36145da",
      "amount": "0.00000000",
      "name": "btc",
      "wallet": "tb1qsclk8wvk7zplp6t8f0954qddctqtvcrhea5gca",
      "rate": 100686.13333333,
      "networkConfig": {
        "btc": {
          "mainnet": false,
          "name": "test",
          "withdrawal": {
            "feeWithdrawal": 0.0003,
            "minWithdrawal": 0.0003
          },
          "deposit": {
            "minDeposit": 0
          }
        }
      }
    }
  ]
}

 

Code: 400
Description: User does not exist

Example response

{
  "errorCode": "P412",
  "errorName": "invalid-user"
}

Get user transaction history

Transaction history can be returned to one year ago. It is returned for the selected month.
Explanation of types:

• exchange - currency exchange
• atmFee - fee charged for ATM transaction
• sepaDeposit - incoming SEPA transfer
• sepaTransfer - outgoing SEPA transfer
• transfer - transfer
• cardTransaction - card transaction
• cryptoDeposit - crypto deposit
• cryptoWithdrawal - crypto withdrawal
• atmWithdrawal - atm withdrawal
• fiatDeposit - fiat deposit
• refund - refund
• cashback - cashback
• payment - card payment
• partialRefund - partial refund
• fiatWithdrawal - fiat withdrawal
• transaction - transaction

Explanation of status:

• SUCCESSFUL - transaction successful
• UNSUCCESSFUL - transaction unsuccessful
• IN_PROGRESS - transaction in progress

Method: GET
Endpoint: /v1/user/transaction-history/:externalUserId/:month/:year

Request

Parameters - required

Name	Type	Required	Example	Description
externalUserId	string	Yes	f9b430dc-7e1a-42a0-bbb4-9003935ea9f9	External user id (from your system)
month	number	Yes	1	Month
year	number	Yes	2025	Year

Response

Code: 200
Description: Returns user transaction history

 

Response body explanation

[
  {
    "createdAt": "Transaction created date",
    "type": "Transaction type",
    "amount": "Transaction amount",
    "amountFrom": "Transaction from amount, if the transaction is an exchange",
    "currency": "Transaction currency",
    "currencyFrom": "Transaction from currency, if the transaction is an exchange",
    "status": "Transaction status"
  }
]

 

Example response

[
  {
    "createdAt": "2025-01-20T10:33:23.808Z",
    "type": "exchange",
    "amount": 0.00220961,
    "amountFrom": -20,
    "currency": "eth",
    "currencyFrom": "doge",
    "status": "SUCCESSFUL"
  },
  {
    "createdAt": "2025-01-20T09:59:38.233Z",
    "type": "exchange",
    "amount": 26.91447658,
    "amountFrom": -10,
    "currency": "doge",
    "currencyFrom": "eur",
    "status": "SUCCESSFUL"
  },
  {
    "createdAt": "2025-01-20T09:35:36.182Z",
    "type": "exchange",
    "amount": 99.9651492,
    "amountFrom": -10,
    "currency": "doge",
    "currencyFrom": "eur",
    "status": "SUCCESSFUL"
  }
]

 

Code: 400
Description: Invalid month or year

Example response

{
  "errorCode": "P403",
  "errorMessage": "
    The month cannot be less than 1,
    The month cannot be longer than 12,
    The year must be the current year or the previous year
  "
}

 

Code: 400
Description: Invalid date

Example response

{
  "errorCode": "P435",
  "errorName": "invalid-date"
}

 

Code: 400
Description: User does not exist

Example response

{
  "errorCode": "P412",
  "errorName": "invalid-user"
}