App2App API

This tutorial is a guide to help Klip Partners use App2App REST API more easily. Since SDKs are based on REST API, you can refer to the explanations below.

Environment Setup

App2App API doesn't require a separate registration process and works in any environments where HTTP communication is possible. But since user's consent is received using the mobile app Klip, you need to have Klip installed to make the requests.

There is no sandbox environment provided at the moment. You can test and implement using actual Klip accounts.

In the examples below, REST APIs can be called using curl, deep links using the APIs of SDKs provided by each mobile environment. Mobile webs can use the Web2App library. The Web2App library is available in the GitHub repository below. Visit the links for more details.

• curl download

• Web2App GitHub repository

If you need help with this document or Klip in general, please visit our [Developer Forum](https://klipforum.zendesk.com).

Step 1: Prepare

The first step in App2App is Prepare, in which you pass the data to Klip and receive a request key. Reqeust key is required to launch a deep link and retrieve the result.

Possible requests are auth, transaction. transaction further consists of KLAY Transfer Transaction, Token Send Transaction, Card Send Transaction, and Contract Execute Transaction. Set the appropriate fields and send a request to the API.

Set the from field with the Klaytn address of the Klip user that signs the transaction. This field is optional, but it is recommended to fill it up because it is used to compare the address with the intended user's.

If you need help with this document or Klip in general, please visit our [Developer Forum](https://klipforum.zendesk.com).

Case 1) Auth Request

Auth request is used to retrieve the EOA of a Klip user. An example is shown below:

curl -X POST "https://global.a2a-api.klipwallet.com/v2/a2a/prepare" \
-d '{"bapp": { "name" : "My BApp" }, "callback": { "success": "mybapp:\/\/klipwallet\/success", "fail": "mybapp:\/\/klipwallet\/fail" }, "type": "auth" }' \
-H "Content-Type: application/json"

Including additional fields like Authorization, Cookie in the API request header may cause a CORS error. Make sure not to add any fields other than the ones described here.

If your request is successful, it returns the following:

{
  "request_key": "0b0ee0ad-62b3-4146-980b-531b3201265d", // random string
  "status": "prepared", // Return "error" in case of a problem.
  "expiration_time": 1600011054 //unix timestamp
}

Set the success field in the callback object with a deep link that takes one back to the BApp after the request is processed. The fail field is also set with a deep link that brings one back in case of a failure due to insufficient balance. You don't have to set this up when the BApp doesn't support deep link. In this case, the process is complete when the user is brought back from Klip to BApp.

Case 2) Send KLAY Request

Send KLAY request is used to send Klip Wallet user's KLAY to designated people.

curl -X POST "https://global.a2a-api.klipwallet.com/v2/a2a/prepare" \
-d '{"bapp": { "name" : "My BApp" }, "type": "send_klay", "transaction": { "from": "0xcD1722f2947Def4CF144679da39c4C32bDc35681", "to": "0x85c17299e9462e035c149847776e4edb7f4b2aa9", "amount": "100" } }' \
-H "Content-Type: application/json"

to takes the address to receive KLAY and amount is the KLAY to send. You can enter the amount up to the 6th decimal place.

If the request is succesful, it returns the same result as that of an Auth request.

Case 3) Send Token Request

The Send Token Request is used to send a Klip user's tokens to a specified address. An example is shown below:

curl -X POST "https://global.a2a-api.klipwallet.com/v2/a2a/prepare" \
-d '{"bapp": { "name" : "My BApp" }, "type": "send_token", "transaction": { "contract": "0xdc8c8d2CD5829dE8e8a31Fc595D69c4B403e9dD8", "from": "0xcD1722f2947Def4CF144679da39c4C32bDc35681", "to": "0x85c17299e9462e035c149847776e4edb7f4b2aa9", "amount": "100" } }' \
-H "Content-Type: application/json"

You need to set the contract field of the transaction object with the SCA of a token provided by Klip. A token not supported on Klip will cause an error. Set the amount field with the amount of the tokens to send. You can enter the amount up to the 6th decimal place.

If the request is succesful, it returns the same result as that of an Auth request.

Case 4) Send Card Request

The Send Card Request is used to send a Klip user's Card to a specified address. An example is shown below:

curl -X POST "https://global.a2a-api.klipwallet.com/v2/a2a/prepare" \
-d '{"bapp": { "name" : "My BApp" }, "type": "send_card", "transaction": { "contract": "0xB21F0285d27beb2373ECB5c17E119ccEAd7Ee10A", "from": "0xcD1722f2947Def4CF144679da39c4C32bDc35681", "to": "0x85c17299e9462e035c149847776e4edb7f4b2aa9", "card_id": "1234" } }' \
-H "Content-Type: application/json"

You need to set the contract field of the transaction object with the SCA of a Card provided by Klip. A Card not supported on Klip will cause an error. Set the card_id field with the ID of the Card to send.

If the request is succesful, it returns the same result as that of an Auth request.

Case 5) Execute Contract Request

The Execute Contract Request is used to execute the functionf of a specified smart contract using a Klip user's signature. An example is shown below:

curl -X POST "https://global.a2a-api.klipwallet.com/v2/a2a/prepare" \
-d '{"bapp": { "name" : "My BApp" }, "type": "execute_contract", "transaction": { "to": "0xd4fFbe967c31C29199478Be2b5A53dC69eF9B825", "value": "0", "abi": "{ \"constant\": false, \"inputs\": [ { \"name\": \"a\", \"type\": \"string\" } ], \"name\": \"testString\", \"outputs\": [], \"payable\": false, \"stateMutability\": \"nonpayable\", \"type\": \"function\" }", "params": "[\"test_string\"]" } }' \
-H "Content-Type: application/json"

You need to set the contract field of the transaction object with the SCA. Set the value field with the KLAY to send in peb. This is only possible with a payable function. Enter the ABI of the function in abi. Set params with the array of parameters that executed this function. Note that the fields abi and params are String types.

If the request is succesful, it returns the same result as that of an Auth request. If you need help with this document or Klip in general, please visit our Developer Forum.

Step 2: Request

Request is a process of initiating a deep link to request Klip to process App2App request. When Klip is opened through a deep link, the user will see an confirm window. For an Auth request, the user will be asked to give consent to providing his/her EOA to the BApp. For transaction requests, the relevant transaction data will be displayed on the screen, and the transaction will be processed after receiving the PIN.

If you set up a callback deep link in the Prepare step, it will redirect automatically to the BApp. Otherwise, the user will be provided with a notification message to return to the BApp.

Klip provides deep links for the following environments. For all of the environments, you need to pass request_key as a query string, which you obtained in the Prepare step.

If you need help with this document or Klip in general, please visit our [Developer Forum](https://klipforum.zendesk.com).

Case 1) iOS Environment

klip://klipwallet/open?url=https://global.klipwallet.com/?target=/a2a?request_key=0b0ee0ad-62b3-4146-980b-531b3201265d

The klip URL scheme can be detected by the BApp using an API provided by iOS. The link that redirects to the Klip download link in case it is not installed is shown below:

itms-apps://itunes.apple.com/app/id362057947

Case 2) Android Environment

intent://klipwallet/open?url=https://global.klipwallet.com/?target=/a2a?request_key=0b0ee0ad-62b3-4146-980b-531b3201265d#Intent;scheme=klip;package=com.klipwallet.global;end

The klip URL scheme can be detected by the BApp using an API provided by Android. The link that redirects to the Klip download link in case it is not installed is shown below:

market://details?id=com.klipwallet.global

If you are developing your BApp for mobile web, using the Web2App library can be convenient.

Step 3: Result

The final status of the App2App API request can be obtained by polling the Result API. You need to pass the request_key as a query string which you obtained in the Prepare step.

curl -X GET "https://global.a2a-api.klipwallet.com/v2/a2a/result?request_key=0b0ee0ad-62b3-4146-980b-531b3201265d" \
-H "Content-Type: application/json"

If the request is successful, it returns the corresponding result for each type as shown below:

Case 1) Auth Request

{
  "request_key": "0b0ee0ad-62b3-4146-980b-531b3201265d",
  "expiration_time": 1600011054,
  "status": "completed",
  "result": {
    "klaytn_address": "0x85c17299e9462e035c149847776e4edb7f4b2aa9"
  }
}

Case 2) Requests other than Auth

{
  "request_key": "0b0ee0ad-62b3-4146-980b-531b3201265d",
  "expiration_time": 1600011054,
  "status": "completed",
  "result": {
    "tx_hash": "0x82d018556e88b8f8f43dc2c725a683afc204bfd3c17230c41252354980f77fb3",
    "status": "success"
  }
}

For requests other than Auth, there is also the result object in the response. You can use the tx_hash in the result object to check the transaction status at Klaytnscope. If the status in result reads pending, it means that the transaction has been confirmed by the user in Klip, but is still being processed on Klaytn. Normally, you should be able to see it in a few seconds. success is returned when the request is successful, and fail은 when the request is unsuccessful.

If you need help with this document or Klip in general, please visit our [Developer Forum](https://klipforum.zendesk.com).

Get Additional Information

To be able to send Cards in a BApp, you often need to retrieve the user's list of Cards and obtain the ID. You can retrieve the Card list of a user using the EOA obtained from the Auth request and the contract address as parameters.

An example is shown below:

curl -X GET "https://global.a2a-api.klipwallet.com/v2/a2a/cards?sca=0xB21F0285d27beb2373ECB5c17E119ccEAd7Ee10A&eoa=0x85c17299e9462e035c149847776e4edb7f4b2aa9&cursor=" -H "Content-Type: application/json"

If the request is successful, it returns the following:

{
    "name": "conan",
    "symbol_img": "https://media.klipwallet.com/token_icon/klay_klip.svg",
    "cards": [
    {
      "created_at": 1580176787,
      "created_at_format": "format",
      "updated_at": 1580176787,
      "updated_at_format": "format",
      "owner": "0x85c17299e9462e035c149847776e4edb7f4b2aa9",
      "sender": "0x2412b300750f505fb2e68ddf0cd45e9d95f5378d",
      "card_id": 19,
      "card_uri": "https://media.klipwallet.com/card-asset/1234/19.json",
      "transaction_hash": "0x293a2e53ecf238109908e65a2b7ff4aad0919ce3ce54af08d6fc4323f28e935d"
    },
    ],
    "next_cursor": "mrzedXOE9OeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL"
}

If the request is successful, it will return the list of Cards in a BApp and their information.

• card from cardsrefers to Klip Card used in this BApp. BApp contains one type of Card.

• You must use either cursor or isAll as query parameter (You can use cursor if isAll is false).

• If you use cursor, Pagination will be used.

  • You can receive information of 100 Cards per one request.

  • If the number of Cards to query exceeds 100, you can retrieve the rest of the Cardi information using next_cursor, which is the pointer from which to return the next 100 objects.

  • To retrive the rest of the Card information, set the cursor parameter with next_cursor and make another request to the same endpoint.

In the example above, the response contains cards.next_cursor, meaning that this account holds over a 100 conan Cards. If the number of Cards to query exceeds 100, the reponse will only contain 100 Cards per request along with the cards.next_cursor. To retrieve the rest of the Card information, set the cursor parameter with cards.next_cursor and make another request to the same endpoint.

For example, if there are a total of 150 Cards from which to retrieve information, the request will return the information of 100 Cards and the cards.next_cursor. You can retrieve the information of the remaining 50 Cards, by setting the cursor parameter with the cards.next_cursor from the previous step and make another request to the same endpoint.

If the request is not successful, it returns the HTTP status codes 400 or 500. For more details, please refer to Basics. If you need help with this document or Klip in general, please visit our Developer Forum.