API Documentation

Basic API flow

In this section you’ll be able to see a basic flow of Koywe’s API calls for purchase and selling (applies for both actions).

/accounts

This service is only for customers who have delegated KYC.
The account to create or update will be based on the email provided in the request. This can be done from the body or through the token. If they are sent from both sides, they must be the same.

Glossary

  • email: Email address that will be associated with the user’s account.
  • document:- documentNumber: Document number belonging to the person who is going to register. - documentType: Type of document related to the document number of the person who is going to register. - country: Country of issuance of the document. - isCompany: Type of person to register. If set to true, the account to be registered will be for a legal entity. Otherwise, it will be for a natural person. - others: Array of secondary documents. - documentNumber: Document number belonging to the person who is going to register. - documentType: Type of document related to the document number of the person who is going to register. - country: Country of issuance of the document.
  • address:- addressCountry: Place of residence of the person. It cannot be different from the one in the document. - addressZipCode: Postal code of the residence. - addressState: Name of the first subdivision of the country of residence. Could be a state, province, region, etc. - addressCity: Name of the city of residence. - addressNeighborhood: Name of the subdivision of the city. Could be a neighborhood, commune, etc. - addressStreet: Street address with numbering, if it has one, where the person, legal or natural resides.
  • personalInfo:- names: Names of the individual or trade name of the legal entity. - firstLastname: First surname of the individual. Not applicable for legal entity. - secondLastname: Second surname of the individual. Not applicable for legal entity. - nationality: Nationality of the individual. Not applicable for legal entity. - gender: Gender of the individual. Could be M for male, F for female, or O for other. Not applicable for legal entity. - dob: Date of birth of the person or date of commencement of activities for a legal entity. It is in the format YYYY-MM-DD. - phoneNumber: Contact number associated with the person related to the country of registration. - activity: Profession of the individual or activity carried out by the legal entity.

Supported countries

ARG, CHL, COL, MEX, PER

Types of documents by supported country

  • Argentina -> DNI y CUIT
  • Chile -> RUT
  • Colombia -> National ID (CED_CIU), Foreigner ID card (CED_EXT) y NIT
  • México -> RFC y CURP
  • Perú -> DNI y RUC

Supported nationalities

  • ATG: Antigua y Barbuda
  • ARG: Argentina
  • BHS: Bahamas
  • BRB: Barbados
  • BLZ: Belice
  • BOL: Bolivia
  • BRA: Brasil
  • CAN: Canadá
  • CHL: Chile
  • COL: Colombia
  • CRI: Costa Rica
  • CUB: Cuba
  • DMA: Dominica
  • DOM: República Dominicana
  • ECU: Ecuador
  • SLV: El Salvador
  • GRD: Granada
  • GTM: Guatemala
  • GUY: Guyana
  • HTI: Haití
  • HND: Honduras
  • JAM: Jamaica
  • MEX: México
  • NIC: Nicaragua
  • PAN: Panamá
  • PRY: Paraguay
  • PER: Perú
  • PRI: Puerto Rico
  • KNA: San Cristóbal y Nieves
  • LCA: Santa Lucía
  • VCT: San Vicente y las Granadinas
  • SUR: Surinam
  • TTO: Trinidad y Tobago
  • USA: Estados Unidos
  • URY: Uruguay
  • VEN: Venezuela
  • AIA: Anguila(Reino Unido)
  • ABW: Aruba(Países Bajos)
  • BMU: Bermudas(Reino Unido)
  • BES: Bonaire, San Eustaquio y Saba(Países Bajos)
  • CYM: Islas Caimán(Reino Unido)
  • SGS: Islas Georgias del Sur y Sandwich del Sur(Reino Unido)
  • GRL: Groenlandia(Dinamarca)
  • GLP: Guadalupe(Francia)
  • FLK: Islas Malvinas(Reino Unido)
  • MTQ: Martinica(Francia)
  • MSR: Montserrat(Reino Unido)
  • ANT: Antillas Neerlandesas(Países Bajos)
  • TCA: Islas Turcas y Caicos(Reino Unido)
  • VGB: Islas Vírgenes Británicas(Reino Unido)
  • VIR: Islas Vírgenes de los Estados Unidos(.UU)

/Auth

First, you need to authenticate. For this, you have two ways:

  • Directly, if you are already a client, you can do it with a secret and the clientId using the POST /auth service. We suggest adding the user’s email to use the JWT in the following calls.
  • Only available for customers with non-delegated KYC. In a two-step process, through email by consuming the POST /auth/validate endpoint. We will send you a code to validate it and then confirm it with POST /auth/code.

GetCurrencyTokens (on ramp) GetTokenCurrency (off ramp)

Returns the list of pairs to check available currencies and tokens and display them to the user.

/payment-providers for on ramp

On ramp: Returns the list of available payment methods. In this endpoint, you will find the transfer data for each country, so it might be a good time to show them to the user if they select that payment method.

Off ramp: It is not required.

/bank-accounts

Bank account registration.

On ramp: Required only if using the STP payment method.

Off ramp: Required. Before being able to create an order, we need to register the bank account where the money will be sent.

Post /quotes

Having the inputs for both fiat and crypto, the user must input the amount he desires to pay or receive in order to obtain a quote. Once the call’s response is retrieved, the user will be able to know exactly how much they’ll pay in fees and how much they’ll receive. Optionally, we can ask the API to keep the quote valid for a few of seconds. If that is the case, quoteId can be kept to use in the next step.

Test it!
Request
$  curl --location --request POST 'https://api.koywe.com/rest/quotes' \
>  --header 'Content-Type: application/json' \
>  --data-raw '{
>      "amountIn": 1000,
>      "symbolIn": "USDC Polygon",
>      "symbolOut": "CLP",
>      "executable": false
>  }'

By adding an authentication JWT in the header and executable: true to the request, you will get a quoteId that can be used to create the order in the next step. This quote lasts for 5 minutes.

Post /orders

Confirming the order is enough. If the quoteId is still valid, the only additional parameters are the wallet address or bank account details, the user’s documentNumber, and, optionally, a metadata field to identify the order on your system.

For off ramps, you will need to create a bank account for the user. Check the docs to see how to do this. The bankAccount id should be added to the destinationAddress field.

Test it!
Request
$  curl --location --request POST 'https://api.koywe.com/rest/orders' \
>  --header 'Content-Type: application/json' \
>  --header 'Authorization: Bearer superJWT' \
>  --data-raw '{
>      "quoteId": "64c9a26af1fada33f2e9e5d7",
>      "destinationAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
>      "metadata": "Sending some USDC to Vitalik",
>      "documentNumber": "111243235"
>  }'

The API will return an orderId, the payment details (a url to redirect your user to or the wire transfer details), and information for you to follow up the process. It should look something like this:

1{
2  "data": {
3    "createOrder": {
4      "amountIn": 822000,
5      "amountOut": 1000,
6      "documentNumber": "111243235",
7      "email": "email@domain.com",
8      "metadata": "Sending some USDC to Vitalik",
9      "orderId": "27d1a1c0-ff5e-4d5a-8893-a3ac2bb121e7",
10      "providedAction": "https://url.to/some-path", // This should be a URL to a payment method or the callback you provided
11      "providedAddress": "Koywe SpA\nCta Cte 6824645\n76.215.256-2\nBanco Santander\ntef@koywe.com", // where to transfer the money, in case of wire
12      "symbolIn": "CLP",
13      "symbolOut": "USDC"
14    }
15  }
16}

If the quote has expired, a new one can be generated (required from November 1, 2023) or make a call to createOrder with the same parameters to obtain a quote and a order at the same time.

Once the orderId is received you can save it, associating it to the user.

The only thing left to do is to wait for the calls to your from our API or check every now and then with Get /order providing the orderId.

For off-ramp operations in Argentina, they are generally effective immediately. However, the status of the order will not change to delivered until 4 days have passed since the corresponding cryptocurrencies for the created order were deposited.