App2App

This page explains how to use App2App REST API to integrate Klip to your BApp.

※ Introduction

There are three steps involved in using App2App API: Prepare, Request, and Result.

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

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 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, figma)

• Klip App2App Button Template Download

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.

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.

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.

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.

Authentication or signature will be requested on Klip via deep link.

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

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

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 will be launched. In the request_key field, use the request key obtained in the Prepare step.

klip://klipwallet/open?url=https://global.klipwallet.com/?target=/a2a?request_key=9892...4aeb

IntentURI for Android looks like this:

intent://klipwallet/open?url=https://global.klipwallet.com/?target=/a2a?request_key=9892...4aeb#Intent;scheme=klip;package=com.klipwallet.global;end

※ API Specification

Below is the specification for App2App API.

Prepare

POST https://global.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:

200

{
  "request_key": "random key",
  "status": "prepared",
  "expiration_time": 12345 //unix timestamp
}

400

500

** bapp Object Sample **

{
  "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

{
  "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

{
  "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

{
  "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

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

Although from is optional, it is recommended to test that the Klip user is the actual intended user for the transaction.

Request Example

curl -X POST "https://global.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.

status can be one of the following: prepared, requested, completed, canceled, or error. canceled is set when the user intentionally cancels the App2App process.

Please refer to our Tutorial for more details. If you need help with this document or with Klip in general, please visit our Developer Forum.

Request

DEEP LINK klip://klipwallet/open?url=https://global.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 klip:// 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.

200

Request Example

The request_key field is set with the value obtained in the Prepare step.

iOS

klip://klipwallet/open?url=https://global.klipwallet.com/?target=/a2a?request_key=9892...4aeb

Android

intent://klipwallet/open?url=https://global.klipwallet.com/?target=/a2a?request_key=9892...4aeb#Intent;scheme=klip;package=com.klipwallet.global;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://global.klipwallet.com/?target=/a2a?request_key=9892...4aeb

QR Code Sample

Refer to the following open source projects on creating QR codes:

• JavaScript : https://www.npmjs.com/package/qrcode

• Android : https://github.com/zxing/zxing

• iOS : https://github.com/EFPrefix/EFQRCode

Result

GET https://global.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.

200

{
  "request_key": "random key",
  "expiration_time": unix timestamp,
  "status": "requested" or "completed",
  "result": {
    "klaytn_address": string
  }
}

400

500

Request Example

curl -X GET "https://global.a2a-api.klipwallet.com/v2/a2a/result?request_key=9892...4aeb" \
-H "Content-Type: application/json"

Response Details

1. type: auth

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

status can be one of the following: prepared, requested, completed, canceled, or error. canceled is set when the user intentionally cancels the App2App process.

1. type: Types other than auth

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

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.

Please refer to our Tutorial for more details. If you need help with this document or with Klip in general, please visit our Developer Forum.

Get Card Information

GET https://global.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.

200

{
    "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",
      "card_id": 19,
      "card_uri": "metadata uri",
      "transaction_hash": "0x293a2e53ecf238109908e65a2b7ff4aad0919ce3ce54af08d6fc4323f28e935d"
    },
    ],
    "next_cursor": string
}

400

500

Request Example

curl -X GET "https://global.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 objects 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.
sender	string	The EOA 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 for more details. If you need help with this document or with Klip in general, please visit our Developer Forum.