Quickstart

Quickstart with Mercuryo SDK

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.

Android

Gradle

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

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

Add dependency:

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

iOS

CocoaPods

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

target :YourTargetName do
    pod 'Mercuryo-SDK'
end

Manual Installation

• Download archive and extract the zip.

• Drag MercuryoSDK.xcframework into your project.

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

• 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.

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.

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:

Debugging

To debug methods using SDK you'd need:

Android

Add Napier logger library (Read more at https://github.com/AAkira/Napier) – add isDebug parameter in .create method:

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

iOS

Init SDK by following method and set isDebug = true

IMercuryo(isDebug: Bool, baseHost: String?)

Initialize the session with Access Token

To initialize the session with Access Token use the following:

Kotlin

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

Swift

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

Wallets

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.

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?)
}

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...
}

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:

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

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
}

Cards

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

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

Kotlin

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

Swift

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

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

Kotlin

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

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
}

SDK models reference

Read more regarding SDK models in our SDK Models Reference

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/).