> For the complete documentation index, see [llms.txt](https://mercuryo.gitbook.io/mobilesdk-en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mercuryo.gitbook.io/mobilesdk-en/master.md).

# Quickstart

Quickstart with Mercuryo SDK

<div align="left"><img src="https://1054688193-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MTteOf7XXaHz5V5_paW%2F-MTtecV4G-Y_GXNgjAgg%2F-MTtgqoPy456mR75IGI5%2Flogo.png?alt=media&amp;token=aa30525c-4765-47f8-b4b2-19b91a8bce8d" alt=""></div>

## Basics

Mercuryo is a Multicurrency Crypto Wallet allowing users to buy, sell, store and pay with cryptocurrency whenever they want. Besides client-facing web and mobile apps or widgets Mercuryo provides the platform for developers to create their own services on top of our API. This SDK is created to ease the process of integration of top-notch crypto experience to your mobile applications.

Main features of SDK include:

* silently logging user in
* explicitly log user in
* explicitly sign user up using different credentials
* getting user's wallets and balances
* getting actual exchange rates
* getting user's cards
* allowing user to bind new cards
* allowing user to buy, sell crypto using added cards
* allowing user to withdraw and top up crypto using generated addresses.

To integrate Mercuryo Mobile SDK you'd need to contact us and get a unique partner token which will need to be integrated on your backend. This token must be obtained by your mobile application for silent login from the server in secure manner.

## Installation

SDK currently is publicly available for Android and iOS. Follow steps below to install it for your application.

{% tabs %}
{% tab title="Android" %}

### Gradle

Add it in your root build.gradle at the end of repositories:

```groovy
allprojects {
    repositories {
        ...
        maven { url 'https://dl.bintray.com/andrey-timofeev/mercuryo/' }
    }
}
```

Add dependency:

```groovy
dependencies {
    implementation 'io.mercuryo.sdk:core:0.1.8'
}
```

{% endtab %}

{% tab title="iOS" %}

### CocoaPods

Add the Mercuryo-SDK pod into your Podfile and run pod install.

```ruby
target :YourTargetName do
    pod 'Mercuryo-SDK'
end
```

### Manual Installation

* [Download archive](https://github.com/mercuryoio/iOS-SDK/archive/main.zip) and extract the zip.
* Drag `MercuryoSDK.xcframework` into your project.

<div align="left"><img src="https://1054688193-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MTteOf7XXaHz5V5_paW%2F-MTtk19XsqFyWxACGYgw%2F-MTtkjmwX0nxY3NFLoOC%2Fcopy_into_project.png?alt=media&amp;token=f839c447-5ee8-44f0-af79-cc3688cd34b3" alt=""></div>

* Select "Copy items if needed" and click Finish.

<div align="left"><img src="https://1054688193-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MTteOf7XXaHz5V5_paW%2F-MTtk19XsqFyWxACGYgw%2F-MTtlFHM7KnM1FtxinnJ%2Fcopy_dialog.png?alt=media&amp;token=bd2d7efb-2469-4be7-a985-79f26001a924" alt=""></div>

* Don’t forget to change Embed property for MercuryoSDK.xcframework on “Embed & Sign”. This can be found in the “Frameworks, Libraries, and Embedded Content” section of your target’s “General” tab.

<div align="left"><img src="https://1054688193-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MTteOf7XXaHz5V5_paW%2F-MTtk19XsqFyWxACGYgw%2F-MTtlS3X_PTL2gWiWFTX%2Fsetup_guide.png?alt=media&amp;token=e7517e20-fd65-49c9-9c0a-1b80642127db" alt=""></div>
{% endtab %}
{% endtabs %}

## Server Integration

To operate on behalf of the user your app needs to create session providing access token. This token is expected to be obtained from server-to-server communication between your backend application and Mercuryo API.

The API method for silent login receives the following parameters:

* `partner_token` - unique partner token
* `user_phone` - user's phone number with country code.

The method checks whether partner\_token is valid, user with specified user\_phone exists and allowed to log in.

Read more about server-to-server communication [here](https://mercuryo.gitbook.io/silent-login/).

If all the conditions are met the method logs user in and issues an `access_token` in the response which should be passed to SDK.

General data flow is shown below:

![](https://1054688193-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MTteOf7XXaHz5V5_paW%2F-MTtk19XsqFyWxACGYgw%2F-MTtobL7KTBNuAIv26Ae%2Fcommon_flow.png?alt=media\&token=04607e3a-5108-42e8-baa8-bca96079376b)

## Debugging

To debug methods using SDK you'd need:

{% tabs %}
{% tab title="Android" %}
Add Napier logger library (Read more at <https://github.com/AAkira/Napier>) – add `isDebug` parameter in `.create` method:

```kotlin
Mercuryo.create(application: Application,
    baseHost: String? = null,
    isDebug: Boolean = true
)
```

{% endtab %}

{% tab title="iOS" %}
Init SDK by following method and set `isDebug = true`

```swift
IMercuryo(isDebug: Bool, baseHost: String?)
```

{% endtab %}
{% endtabs %}

## Initialize the session with Access Token

To initialize the session with Access Token use the following:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
val mercuryo: Mercuryo = Mercuryo.create(...)  
val sessionManager: SessionManager = mercuryo.session
sessionManager.updateToken(token: String)
```

{% endtab %}

{% tab title="Swift" %}

```swift
var mercuryoSDK: IMercuryo = IMercuryo(isDebug: true, baseHost: "HOST_HERE")
var sessionManager: IosSessionManager: mercuryoSDK.session
session.updateToken(token: String)
```

{% endtab %}
{% endtabs %}

## Wallets

<div align="left"><img src="https://1054688193-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MTteOf7XXaHz5V5_paW%2F-MTtk19XsqFyWxACGYgw%2F-MTtw6nQsD-ro_utpffi%2Fwallet.png?alt=media&amp;token=bfc9f735-93b1-4027-a0ee-113931bcaa6a" alt=""></div>

Mercuryo user has several wallets for each crypto currency with a correspondent balance. You may decide yourself which wallet is shown or hidden but these methods allow you to get whole state of user's balances.

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
val wallet = mercuryo.wallet

CoroutineScope.launch{
    val wallets: List<Wallet> = wallet.getWallets()
    val transactions: List<Transaction> = wallet.getTransactions(type: TransactionType? , limit: Int, offset: Int, currency: String?)
}
```

{% endtab %}

{% tab title="Swift" %}

```swift
var wallet = mercuryoSDK.wallet

wallet.getWallets { wallets, error in
    // do some magic here...
}
wallet.getTransactions(type: nil, limit: 20, offset: 0, currency: "CRYPTO_CURRENCY HERE") { transactions, error in
    // do some magic here...
}
```

{% endtab %}
{% endtabs %}

## Operations

For buying and selling crypto on behalf of the user you should perform the following steps:

* initialize buying or selling session
* provide currencies, amount, fix rate by obtaining so-called buying or selling token which is valid for several minutes
* make transaction providing card id, card CVV
* if needed, ask for additional verification, i.e. descriptor code.

For example, the following methods may be used for buying crypto providing user's card:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
val mercuryo: Mercuryo = Mercuryo.create(...)  
val buy: Buy = mercuryo.operations.buy

CoroutineScope.launch{
    val result: ConverterResult = buy.convert(
        fromCurrency = "BTC", 
        toCurrency = "EUR", 
        amount = "1"
    )

    val status: TransactionStatus = buy.commit(
        cardId = "yourCardId", 
        cvv = "yourCardCvc", 
        buyToken = result.token, 
        redirectUrl = "http://my.mercuryo.io/orders?invoice={invoice_id}"
    )
}
```

{% endtab %}

{% tab title="Swift" %}

```swift
var buy = mercuryoSDK.operations.buy
var buyToken: String? = nil 

buy.convert(fromCurrency: "BTC", toCurrency: "EUR", amount: 1) { converterResult, error in
    buyToken = converterResult.token
    //do some magic here
}

...

buy.commit(cardId: "CARD_ID HERE", cvv: "CARD_CVV HERE", buyToken: buyToken, redirectUrl: "REDIRECT_URL HERE") { transactionInfo, error in 
    //do some magic here
}

```

{% endtab %}
{% endtabs %}

## Cards

Mercuryo stores user's encrypted cards data allowing users to buy and sell using them.

<div align="left"><img src="https://1054688193-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MTteOf7XXaHz5V5_paW%2F-MTu6zJi51WGDch7NCgH%2F-MTu7CTT95Ikp8XtLAN1%2Fcards.png?alt=media&amp;token=ac6192ae-55e5-4cb2-8ff7-1e4aa0b2a526" alt=""></div>

To get a list of linked cards, call the method:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
cardManager.getCards(limit: Int, offset: Int): List<Card>
```

{% endtab %}

{% tab title="Swift" %}

```swift
mercuryoSDK.card.getCards(limit: 20, offset: 0) { cards, error in
    //do magic here          
}
```

{% endtab %}
{% endtabs %}

Use the following method to add a card to user's account:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
cardManager.bindCard(holderName: String, number: String, cvv: String, expirationMonth: String, expirationYear: String, redirectUrl: String): BindCard
```

{% endtab %}

{% tab title="Swift" %}

```swift
mercuryoSDK.card.bindCard(holderName: "HOLDER_NAME HERE", number: "5536 ...", cvv: "123", expirationMonth: "MM", expirationYear: "YYYY", redirectUrl: "REDIRECT_URL HELE") { bindCardInfo, error in 
    //do magic here
}
```

{% endtab %}
{% endtabs %}

## SDK models reference

Read more regarding SDK models in our [SDK Models Reference](https://mercuryo.gitbook.io/reference-en/#models)

## Roadmap

## Updates and support

If you have any questions or suggestions please create an issue in GitHub, write us in Telegram (<https://t.me/mercuryo_en>) or in Intercom on our website (<https://help.mercuryo.io/>).