# App2App ## ※ Introduction There are three steps involved in using App2App API: **Prepare**, **Request**, and **Result**. {% hint style="warning" %} * Do not impersonate "GroundX" when using Klip API. * Only you are responsible for any consequences arising from using Klip API. GroundX is not responsible for its users or third parties. * Your account may be blocked without prior notice in case of any illegal or abnormal use of Klip API, such as creating unsually high traffic. {% endhint %} ### Prepare This step involves selecting the actions you would like to enable for your BApp. All the actions except for "Authentication" require sending a transaction to the Klaytn network. You therefore have to create a transaction object for these steps. The actions are as follows: * **Authentication** * **Sending KLAY** * **Sending Tokens** * **Sending Cards** * **Executing Smart Contract** #### Authentication This is a process to access a BApp user's Klip wallet. It is used to obtain a Klip user's [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) in a BApp. You should comply with the button style guide below when providing a button to enable this feature. #### Klip Log-In Button Guide * Klip App2App Button Design Guide ([pdf](https://media.klipwallet.com/a2a/klip_A2A_button_guide_ENG_v1.0.0.pdf), [figma](https://www.figma.com/file/sZmlfrwbJL2CNOErBD3vtV/A2A-Button-Design-Guide-v.1.0.0?node-id=0%3A1)) * Klip App2App Button Template [Download](https://media.klipwallet.com/a2a/klip_A2A_button_template_ENG_v1.0.0.zip) {% hint style="warning" %} When enabling this feature, you *must* include a way to disconnect Klip Account, and when doing so must immediately delete all collected EOA data. Nonadherence to this policy may result in the blocking of APIs without prior notice. {% endhint %} #### Sending KLAY This step involves sending KLAY from a BApp Member's Klip Wallet to a Klaytn account address (EOA). A transaction object will be created. #### Sending Tokens This step involves sending FTs (Fungible Tokens) from a BApp Member's Klip Wallet to a Klaytn account address (EOA). A transaction object will be created. #### Sending Cards This step involves sending NFTs (Non-Fungible Tokens) from a BApp Member's Klip Wallet to a Klaytn account address (EOA). A transaction object will be created. #### Executing Smart Contract This step involves executing a smart contract using a Klip account. A transaction object will be created. {% hint style="info" %} A successful Prepare API request will return a request key.\ Request key is used for the steps **Request** and **Result**, where the actions specified during the **Prepare** step will be requested for actual execution. {% endhint %} ### Request The actions specified in the previous **Prepare** step will be executed. All actions other than "Authentication", which is basically importing BApp Member's Klip Wallet Address (EOA) to the BApp, involve obtaining a signature for the transaction. The four actions "Sending Token", "Sending KLAY", "Sending Cards" and "Executing Smart Contract" require that transactions be sent to Klaytn. For this step, these transactions will be signed using Klaytn account keys and then be submitted to the Klaytn network. {% hint style="info" %} Authentication or signature will be requested on Klip via deep link. {% endhint %} For example, when a BApp Member “A” clicks on the button to send tokens to another Member “B”, your BApp will use the App2App API to first authenticate “A”'s Klip Wallet address (can be ommitted) and access “A”'s Klip Wallet. It will then submit a transaction to send tokens or Cards to “B”'s Klaytn account address. ### Result Finally in the **Result** step, you will receive the result or response of the request from the previous step. The API has two forms: whereas the **Prepare** and **Result** steps are RESTful APIs that send a request to the Klip Backend server, the **Request** step creates a deep link to use Klip. There is also a RESTful API request for retrieving Card information. ## ※ API Flow Diagram The basic flow of an App2App process looks like this: ![App2App Flow](/files/BoB4UhK0q61eUAFIjUik) Aside from the API request, retrieving Card Information shares the same flow as other REST API requests. It sends a request to the backend to retrieve information, without involving Klip. This flow is demonstrated below: ![App2App Information API Flow](/files/DY5KR3Hv9P8vynVfemqf) Deep link is implemented via URL Scheme on iOS, and intentURI on Android. URL Scheme is a link that looks like the one below. When a BApp user clicks on it, Klip, located in the More\[…] tab on KakaoTalk, will be launched. In the `request_key` field, use the request key obtained in the **Prepare** step. ``` kakaotalk://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=9892...4aeb ``` IntentURI for Android looks like this: ``` intent://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=9892...4aeb#Intent;scheme=kakaotalk;package=com.kakao.talk;end ``` ## ※ API Specification Below is the specification for App2App API. ## Prepare `POST` `https://a2a-api.klipwallet.com/v2/a2a/prepare` Prepares to process an App2App API request and issues a request key. #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ---------------- | | Content-Type\* | string | application/json | #### Request Body | Name | Type | Description | | -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | bapp\* | object | Information of the BApp that will perform the App2App API request. You can set the name and the callback URL. callback only supports deep links. The `callback` field is optional. Please refer to the example below. | | type\* | string | The request type that the App2App will perform. Authentication is `auth`, Sending KLAY is `send_klay`, Sending Tokens is `send_token`, Sending Cards is `send_card`, and Executing Smart Contract is `execute_contract`. | | transaction | object | The data to be signed. It contains `to`, `amount`, `contract` and etc. and requires that the necessary fields for each request type be set. This field is required for all request types except `auth`. Please refer to the example below: | {% tabs %} {% tab title="200 " %} ```json { "request_key": "random key", "status": "prepared", "expiration_time": 12345 //unix timestamp } ``` {% endtab %} {% tab title="400 " %} {% endtab %} {% tab title="500 " %} {% endtab %} {% endtabs %} \*\* `bapp` Object Sample \*\* ```json { "bapp": { "name": "My BApp", "callback": { // all optional "success": "mybapp://.../success/...", "fail": "mybapp://.../fail/..." } } } ``` `name` is the name of the BApp displayed on the Klip user's screen during authentication or transaction signing. The `success` field under `callback` is a deep link to return to the BApp once user validation on Klip is successful. `fail` is a deep link to return to the BApp in case of failures. The `callback` object is optional. \*\* `transaction` Object Sample \*\* 1. type: `send_klay` ```json { "transaction": { "from": "0x8756...4321", // optional "to": "0x1234...5678", "amount": "100" } } ``` `to` is the Klaytn address of the KLAY recipient. `amount` is the amount of KLAY being sent. `from` is the Klip user's address. `from` is an optional field used to sort out unwanted requests through comparison with Klip users' actual address. 1. type: `send_token` ```json { "transaction": { "contract": "SCA", "from": "0x8756...4321", // optional "to": "0x1234...5678", "amount": "100", } } ``` `contract` is the smart contract address of the token. `to` is the Klaytn account address of the recipient. `amount` is the amount of tokens to receive. `amount` is converted automatically based on the decimals of the contract. For example, a KIP-7 contract (FT contract) has 18 decimals, so `amount` 1 would mean 10^18 tokens in its smallest denomination. `from` is the Klip user's address. `from` is an optional field used to sort out unwanted requests through comparison with Klip users' actual address. 1. type: `send_card` ```json { "transaction": { "contract": "0xA987...4321", "from": "0x8756...4321", // optional "to": "0x1234...5678", "card_id": "100", } } ``` `contract` is the smart contract address of the token. `to` is the Klaytn account address of the Card recipient. `card_id` is the identification number of the Card to be sent. `from` is the Klip user's address. `from` is an optional field used to sort out unwanted requests through comparison with Klip users' actual address. 1. type: `execute_contract` ```json { "transaction": { "from": "0x8756...4321", // optional "to": "0xA987...4321", // contract address "value": "1000000000000000000", // Unit= peb. 1 KLAY "abi": "...", "params": "..." } } ``` `to` is the address of the smart contract to be executed. `value` is the amoung of KLAY to be sent to that contract. The unit is peb. For example, 1 KLAY equals 1000000000000000000 pebs. `abi` is the function data of the contract to be executed. `params` refer to the parameter to be passed to the function. `from` is the Klip user's address. `from` is an optional field used to sort out unwanted requests through comparison with Klip user's actual address. More detailed explanations of `abi` and `params` can be found in the tutorial. {% hint style="info" %} Although `from` is optional, it is recommended to test that the Klip user is the actual intended user for the transaction. {% endhint %} **Request Example** ```bash curl -X POST "https://a2a-api.klipwallet.com/v2/a2a/prepare" \ -d '{"bapp": { "name" : "My BApp" }, "type": "execute_contract" }' \ -H "Content-Type: application/json" ``` **Response Details** | Item | Type | Description | | ---------------- | ------ | ----------------------------------------------------------------------- | | request\_key | string | A unique identifier to specify requests for Request, Result APIs. | | status | string | The current status of the API request. The default value is `prepared`. | | expiration\_time | number | The expiration time of the request key in unix timestamp. | {% hint style="info" %} `status` can be one of the following: `prepared`, `requested`, `completed`, `canceled`, or `error`. `canceled` is set when the user intentionally cancels the App2App process. {% endhint %} Please refer to our [Tutorial](/tutorial/tutorial-a2a-rest-api.md) for more details.\ If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28). ## Request `DEEP LINK` `kakaotalk://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=` There are currently two ways to request authentication or signature on Klip: deep link and QR code. Specific request methods differ for each development environment. Deep link uses `kakaotalk://` for iOS, and `intent://` for Android. And QR code uses a URL of the form: `https://`. Refer to the Request Example below for more details. #### Query Parameters | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | request\_key\* | string | The request key obtained in the **Prepare** step. `request_key` is used to specify each request. | {% tabs %} {% tab title="200 " %} {% endtab %} {% endtabs %} **Request Example** The `request_key` field is set with the value obtained in the **Prepare** step. #### iOS ``` kakaotalk://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=9892...4aeb ``` #### Android ``` intent://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=9892...4aeb#Intent;scheme=kakaotalk;package=com.kakao.talk;end ``` #### PC or Other Devices (QR Code) QR code is generated as a URL as below. Users can process App2App requests by reading a QR code through Klip or the native camera app. ``` https://klipwallet.com/?target=/a2a?request_key=9892...4aeb ``` ![QR Code Sample](/files/13w25Ezp4HADv9Vi0s8V) {% hint style="info" %} Refer to the following open source projects on creating QR codes: * JavaScript : * Android : * iOS : {% endhint %} ## Result `GET` `https://a2a-api.klipwallet.com/v2/a2a/result?request_key=` Returns the result of a specified App2App API request. #### Query Parameters | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | request\_key\* | string | The request key obtained in the **Prepare** step. `request_key` is used to specify each request. | {% tabs %} {% tab title="200 " %} ```json { "request_key": "random key", "expiration_time": unix timestamp, "status": "requested" or "completed", "result": { "klaytn_address": string } } ``` {% endtab %} {% tab title="400 " %} {% endtab %} {% tab title="500 " %} {% endtab %} {% endtabs %} **Request Example** ```bash curl -X GET "https://a2a-api.klipwallet.com/v2/a2a/result?request_key=9892...4aeb" \ -H "Content-Type: application/json" ``` **Response Details** 1. type: `auth` ```json { "request_key": "random key", "expiration_time": unix timestamp, "status": "completed", } ``` | Item | Type | Description | | ---------------- | ------ | -------------------------------------------------------------------------------------------- | | request\_key | string | A unique identifier to specify requests for Request, Result APIs. | | expiration\_time | number | The expiration time of the request key in unix timestamp. | | status | string | The current status of the API request. If the request is successful, it returns `completed`. | {% hint style="info" %} `status` can be one of the following: `prepared`, `requested`, `completed`, `canceled`, or `error`. `canceled` is set when the user intentionally cancels the App2App process. {% endhint %} 1. type: Types other than `auth` ```json { "request_key": "random key", "expiration_time": unix timestamp, "status": "completed", "result": { "tx_hash": string, "status": "success" } } ``` | Item | Type | Description | | ---------------- | ------ | -------------------------------------------------------------------------------------------- | | request\_key | string | A unique identifier to specify requests for Request, Result APIs. | | expiration\_time | number | The expiration time of the request key in unix timestamp. | | status | string | The current status of the API request. If the request is successful, it returns `completed`. | | result | object | Result of the signature request. Returns the transaction hash and transaction status. | {% hint style="info" %} If the `status` field in the `result` object reads `pending`, it means that the transaction is still being processed on Klaytn. Normally, you would be able to see the request processed after a few seconds. `success` means that the request was successful, and `fail` means that it failed. {% endhint %} Please refer to our [Tutorial](/tutorial/tutorial-a2a-rest-api.md) for more details.\ If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28). ## Get Card Information `GET` `https://a2a-api.klipwallet.com/v2/a2a/cards?cursor=` Returns a list of Cards owned by a specified EOA, minted with a specified NFT contract. #### Query Parameters | Name | Type | Description | | ------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | sca\* | string | The address of the smart contract to make the query on. | | eoa\* | string | The address to specify which user EOA's Card information to retrieve. Normally the EOA obtained from a App2App `auth` request will be used. | | cursor | string | The pointer from which to return the next 100 objects. | {% tabs %} {% tab title="200 " %} ```json { "name": "Klip", "symbol_img": "image url", "cards": [ { "created_at": 1580176787, "created_at_format": "format", "updated_at": 1580176787, "updated_at_format": "format", "owner": "0x2412b300750f505fb2e68ddf0cd45e9d95f5378d", "sender": "0x0000000000000000000000000000000000000000", "sender_kakao_id": "kakao_id" "card_id": 19, "card_uri": "metadata uri", "transaction_hash": "0x293a2e53ecf238109908e65a2b7ff4aad0919ce3ce54af08d6fc4323f28e935d" }, ], "next_cursor": string } ``` {% endtab %} {% tab title="400 " %} {% endtab %} {% tab title="500 " %} {% endtab %} {% endtabs %} **Request Example** ```bash curl -X GET "https://a2a-api.klipwallet.com/v2/a2a/cards?sca=0x1234...&eoa=0x9876...&cursor=mrzedXOE9OeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL" \ -H "Content-Type: application/json" ``` **Response Details** | Item | Type | Description | | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------- | | name | string | The name of the contract. | | symbol\_img | string | The URL of the contract symbol image. | | cards | array | The array of the `object`s containing Card information. | | next\_cursor | string | The pointer for the next request, after which the result will be returned. It is returned if the array contains over 100 elements. | **Response Details for** `cards[i]` | Item | Type | Description | | ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------- | | created\_at | number | The time at which the Card was minted. | | updated\_at | number | The time at which the Card was updated. | | owner | string | The address of this [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas). | | sender | string | The [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) address of the Card sender. | | card\_id | number | The ID of the Card. | | card\_uri | string | The URL containing the JSON file of the Card's metadata. | | transaction\_hash | string | The hash of the smart contract transaction that minted the Card. | Please refer to our [Tutorial](/tutorial/tutorial-a2a-rest-api.md) for more details.\ If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://en.docs.klipwallet.com/rest-api/rest-api-a2a.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.