# App2App API

## 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 Klip located in the More\[…] tab in the mobile app KakaoTalk, you need to have KakaoTalk installed to make the requests.

{% hint style="info" %}
There is no sandbox environment provided at the moment. You can test and implement using actual KakaoTalk accounts.
{% endhint %}

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](https://curl.haxx.se/download.html)
* [Web2App GitHub repository](https://github.com/kakao/web2app)

\
If you need help with this document or Klip in general, please visit our \[Developer Forum]\(<https://forum.klaytn.com/c/klip-api/28>).

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

{% hint style="info" %}
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.
{% endhint %}

\
If you need help with this document or Klip in general, please visit our \[Developer Forum]\(<https://forum.klaytn.com/c/klip-api/28>).

### Case 1) Auth Request

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

```bash
curl -X POST "https://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"
```

{% hint style="info" %}
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.
{% endhint %}

If your request is successful, it returns the following:

###

```json
{
  "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.

```bash
curl -X POST "https://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:

```bash
curl -X POST "https://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:

```bash
curl -X POST "https://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:

```bash
curl -X POST "https://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](https://forum.klaytn.com/c/klip-api/28).

## 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://forum.klaytn.com/c/klip-api/28>).

### Case 1) iOS Environment

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

The `kakaotalk` URL scheme can be detected by the BApp using an API provided by iOS. The link that redirects to the KakaoTalk 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://klipwallet.com/?target=/a2a?request_key=0b0ee0ad-62b3-4146-980b-531b3201265d#Intent;scheme=kakaotalk;package=com.kakao.talk;end
```

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

```
market://details?id=com.kakao.talk
```

{% hint style="info" %}
If you are developing your BApp for mobile web, using the [Web2App](https://github.com/kakao/web2app) library can be convenient.
{% endhint %}

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

```bash
curl -X GET "https://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

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

### Case 2) Requests other than Auth

```json
{
  "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](https://scope.klaytn.com/). 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://forum.klaytn.com/c/klip-api/28>).

## 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:

```bash
curl -X GET "https://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:

```json
{
    "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",
      "sender_kakao_id": "1234"
      "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 `cards`refers 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](https://en.docs.klipwallet.com/basics#basics-app2app).\
If you need help with this document or Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).