App2App

이 페이지에서는 BApp에서 Klip을 활용하기 위한 App2App REST API를 설명합니다.

Kaia는 기존의 Klaytn과 Finschia 블록체인 네트워크가 통합되어 운영되는 블록체인의 새 이름입니다. 이에 따라 본 문서는 대부분 Klaytn을 Kaia로 / KLAY를 KAIA로 지칭하지만, 하위 호환성을 위해 기존 호출과 응답에서 사용되던 klaytn, KLAY 등의 키워드는 동일하게 유지되는 점 참고 부탁드립니다.

※ 개요

App2App API를 사용하는 단계는 Prepare, Request, Result 3단계로 구분됩니다.

• Klip API를 사용함에 있어 사용자는 (주)그라운드엑스를 사칭해서는 안됩니다.

• Klip API 사용에 따라 발생하는 모든 책임은 전적으로 사용자에게 있으며, (주)그라운드엑스는 사용자 또는 제3자에 대해 어떠한 책임도 지지 않습니다.

• Klip API 사용자가 과도한 네트워크 트래픽을 발생시키는 시도하는 등 불법 혹은 비정상적인 방식으로 API를 사용하려고 시도하는 경우, 사전 고지없이 API 사용이 차단될 수 있습니다.

Prepare

BApp에서 어떤 작업을 실행하고 싶은지 정의하는 단계입니다. "인증"을 제외한 나머지는 체인에 트랜잭션을 전송하는 작업입니다. 트랜잭션 전송을 위해 Prepare 단계에서는 트랜잭션 객체를 생성합니다. 실행 가능한 작업은 다음과 같습니다.

• 인증

• 토큰 전송

• 카드 전송

• 스마트 컨트랙트 실행

• 메시지 서명

인증

BApp 회원의 Klip 지갑에 접근하기 위한 인증 작업입니다. BApp에서 Klip 사용자의 EOA를 얻어야할 때 사용합니다. 이 기능을 위한 Klip 로그인 버튼을 제공하는 경우, 버튼 스타일과 버튼명은 아래 가이드를 준수해야 합니다.

Klip 로그인 버튼 가이드

• Klip App2App 버튼 제작 가이드 (pdf, figma)

• Klip App2App 버튼 템플릿 다운로드

이 기능을 사용하는 경우, Klip 계정을 연결 해지하는 기능도 반드시 제공해야 하며 해지 시 수집한 사용자 EOA 정보를 즉시 삭제해야 합니다.

위와 같은 조건이 지켜지지 않을 경우, 사전 고지없이 API 사용이 차단될 수 있습니다.

토큰 전송

BApp 회원의 Klip 지갑에서 다른 계정 주소(EOA)로 토큰(Fungible Token)을 전송하는 작업입니다. 토큰 전송을 위한 트랜잭션 객체를 생성합니다. 컨트랙트 주소에 0x0000000000000000000000000000000000000000 값을 입력하면 네이티브 코인 (KAIA, ETH, MATIC 등) 전송이 가능합니다.

카드 전송

BApp 회원의 Klip 지갑에서 다른 계정 주소(EOA)로 카드(Non-Fungible Token)을 전송하는 작업입니다. 카드 전송을 위한 트랜잭션 객체를 생성합니다.

스마트 컨트랙트 실행

Klip 계정으로 스마트 컨트랙트를 실행하는 작업입니다. 컨트랙트 실행을 위한 트랜잭션 객체를 생성합니다.

메시지 서명

Klip 계정으로 메시지를 서명하여 반환합니다.

Prepare API 호출에 성공하면 응답값으로 “인증키"(Request Key)를 받습니다. 인증키는 Prepare 단계에서 정의한 작업을 실제로 실행하도록 요청하는 "Request"와 결과를 확인하는 "Result" 단계에서 사용합니다.

Request

위 단계에서 정의한 작업을 실제로 실행하도록 요청합니다.

"인증"은 BApp 회원의 Klip 지갑 주소(EOA)를 BApp으로 받아오는 작업이며 그 외에 나머지 작업은 위 트랜잭션에 서명(sign)을 받는 작업입니다. 이들 4가지 작업은 사실 체인에 트랜잭션 전송을 요청하는 작업이며 토큰 전송, KAIA 전송, 카드 전송, 스마트 컨트랙트 실행 트랜잭션을 체인에 전송합니다. 이 단계에서는 이들 트랜잭션에 계정 키로 서명한 다음 체인에 전송합니다.

인증 또는 서명은 Deep Link를 통해 Klip에 요청합니다.

예를 들어, BApp 회원 “A”가 다른 BApp 회원 “B”에게 토큰 또는 아이템을 전송하는 버튼을 클릭하면 여러분의 BApp은 App2App API를 사용해 “A”의 Klip 지갑 주소를 인증(이미 확보하고 있다면 생략 가능)하고 “A”의 Klip 지갑에 접근합니다. 그리고 전송하려는 토큰 또는 카드를 “B”의 계정 주소에 전송하는 트랜잭션을 보냅니다.

Result

마지막으로 Result 단계는 Request 단계에서 요청한 작업을 실행했을 때 결과 또는 응답값을 얻는 단계입니다.

API는 형태에 따라서 두 가지로 구분할 수 있습니다. 먼저 Prepare와 Result 스텝은 Klip Backend 서버로 요청을 날리는 REST API 형태이고, Request 스텝은 Klip을 띄워서 처리하기 위한 Deep Link 형태입니다. 앞선 두 가지와 별개로 필요 시 사용자의 카드 소유 정보를 얻기위한 REST API 형태의 요청이 있습니다.

※ API Flow Diagram

App2App 처리를 위한 대략적인 흐름은 아래 그림과 같습니다.

App2App Flow

API 요청과 별개로 카드 정보 조회는 일반적인 REST API 호출 흐름과 동일합니다. Klip 거치지 않고 Backend에 요청하여 정보를 받아옵니다. 흐름은 아래와 같습니다.

App2App Information API Flow

Deep Link는 아래와 같은 형태의 링크이고, BApp 유저가 클릭했을 때 클립 앱을 실행하거나 설치할 수 있도록 유도됩니다. request_key 필드에는 Prepare 과정에서 응답으로 전달받은 값을 사용합니다.

https://klipwallet.com?target=/a2a?request_key=9892...4aeb

※ API Specification

App2App API 세부 스펙은 아래와 같습니다.

Prepare

POST https://a2a-api.klipwallet.com/v2/a2a/prepare

App2App API 요청 처리를 준비하고 request key를 발급합니다.

Headers

Name	Type	Description
Content-Type*	string	application/json

Request Body

Name	Type	Description
chain	string	App2App API 요청을 수행할 체인 정보입니다. klaytn, ethereum, polygon 등 세 종류의 체인을 지원하며 기본값은 klaytn입니다. 아래 예시를 참고하십시오. 실제로는 Kaia 체인과 상호작용하지만 호환성 유지를 위해 klaytn 명칭이 사용됩니다.
bapp*	object	App2App API 요청을 수행할 BApp 정보입니다. 이름과 callback URL로 Deep Link를 함께 전달할 수 있습니다. callback 필드는 옵셔널입니다. 아래 예시를 참고하십시오.
type*	string	App2App API 요청 type입니다. 인증은 auth, 코인 및 토큰 전송은 send_token, 카드 전송은 send_card, 메시지 서명은 sign_message 또는 sign_message_eip191 마지막으로 컨트랙트 실행은 execute_contract입니다.
transaction	object	서명할 데이터입니다. to, amount, contract 등의 정보가 들어가며 전송 요청 type별로 필요한 필드를 세팅해야합니다. auth, sign_message를 제외한 요청 타입은 이 필드를 필수적으로 기입해야합니다. 아래 예시를 참고하십시오.
message	object	서명할 데이터입니다. from과 value 값을 포함하며 from은 생략 가능합니다. sign_message 타입인 경우 이 필드를 필수적으로 기입해야 합니다. 그 외의 타입에서는 설정하지 않습니다. 아래 예시를 참고하십시오.

200

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

400

500

bapp object 예시

{
  "bapp": {
    "name": "My BApp",
    "callback": { // all optional
      "success": "myApp://...", // Android 플랫폼의 경우, "intent://..." 로 작성
      "fail": "myApp://..." // Android 플랫폼의 경우, "intent://..." 로 작성
    },
   "kas_authorization_key": "Basic abcdefghijklmnopqrstuvwxyz0123456789="
  }
}

name은 인증 또는 서명 시 Klip 사용자 화면에 표시될 BApp의 이름입니다. callback의 success 필드는 Klip에서 사용자 확인이 성공적으로 처리됐을 때 BApp으로 돌아가기 위한 Deep Link입니다. fail은 반대로 실패한 경우 BApp으로 돌아가기 위한 Deep Link입니다. Android 플랫폼의 경우, Intent Scheme 형식(intent://..)의 Deep Link로 작성이 필요합니다. callback 객체는 optional입니다. kas_authorization_key 는 optional이며, BApp에서 트랜잭션 수수료를 대납하고자 할 경우 사용하는 KAS (Klaytn API Service) 인증 정보입니다. KAS 대납 서비스 구독 및 authorization key 발급 방법은 이 문서를 참고하시기 바라며, 문의사항은 KAS 헬프센터를 이용하여 주시기 바랍니다.

transaction object 예시

1. type: send_token

{
  "transaction": {
    "contract": "SCA",
    "from": "0x8756...4321", // optional
    "to": "0x1234...5678",
    "amount": "100",
  }
}

contract는 토큰의 스마트 컨트랙트 주소입니다 (네이티브 코인의 경우 0x0000000000000000000000000000000000000000 입력). to는 토큰을 전송받는 사람의 계정 주소입니다. amount를 받을 토큰 양입니다. 참고로, amount는 컨트랙트 내 decimal을 반영하여 자동으로 환산되는 수치입니다. 예를 들면, 18 decimal의 FT 컨트랙트에서 amount 1은 10^18 개의 최소 단위 토큰을 의미하게 됩니다. from은 Klip 사용자의 주소입니다. from은 optional 필드이고 Klip 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다.

2. type: send_card

{
  "transaction": {
    "contract": "0xA987...4321",
    "from": "0x8756...4321", // optional
    "to": "0x1234...5678",
    "card_id": "100",
  }
}

contract는 NFT의 스마트 컨트랙트 주소입니다. to는 카드를 전송받는 사람의 주소입니다. card_id는 전송할 카드의 고유번호입니다. from은 Klip 사용자의 주소입니다. from은 optional 필드이고 Klip 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다.

3. type: execute_contract

{
  "transaction": {
    "from": "0x8756...4321", // optional
    "to": "0xA987...4321", // contract address
    "value": "1000000000000000000", // 단위는 실제 트랜잭션의 value 단위와 동일
    "abi": "...",
    "params": "...",
    "encoded_function_call": "0x123...23fe23"
  }
}

to는 실행할 스마트 컨트랙트 주소입니다. value는 해당 컨트랙트에 전송할 코인의 수량입니다. value의 단위는 실제 해당 체인의 트랜잭션 생성 인자와 동일합니다. Kaia 기준으로 단위는 kei이며, 1 KAIA는 1000000000000000000 (10^18) kei입니다. abi는 실행할 컨트랙트 함수 정보입니다. params는 해당 함수에 넘겨줄 인자값입니다. 최신 버전 부터는 tuple 타입도 지원합니다. abi 와 param 대신에 encoded_function_call을 사용할 수 있습니다. encoded_function_call 에 tx의 data에 들어갈 정보를 입력해주면 해당 값을 사용하여 tx를 실행합니다. abi, param 혹은 encoded_function_call 중 하나만을 사용하여 tx를 실행하기 때문에 사용하지 않는 값은 비워져 있어야 합니다. from은 Klip 사용자의 주소입니다. from은 optional 필드이고 Klip 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다. abi 및 params 의 구체적인 예시는 튜토리얼을 참조하십시오.

from은 optional 필드이지만 트랜잭션 처리 시 원래 의도했던 Klip 사용자가 맞는지 검증하는 용도로 사용되므로 가능하면 설정하는 것을 권장합니다.

message object 예시

1. type: sign_message

{
 "message": {
  "from": "0x8756...4321", // optional
  "value": "message original", // 서명할 원문
  "is_hex_encoded": true or false // optional. default는 false.
 }
}

from은 Klip 사용자의 주소입니다. Klip 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다. 선택 항목이므로 생략할 수 있습니다. is_hex_encoded는 메시지 원문의 데이터 타입입니다. true 일 경우 서명 값을 데이터의 hex encoding 된 byte 배열로 판단하여 서명합니다. 생략하거나 false 일 경우는 문자열로 판단합니다. value는 서명할 메시지의 원문입니다. is_hex_encoded 가 true 일 경우 0x 로 시작하는 hex encoding된 byte 배열이여야 합니다.

2. type: sign_message_eip191

{
 "message": {
  "from": "0x8756...4321", // optional
  "value": "message original", // 서명할 원문
  "is_hex_encoded": true or false // optional. default는 false.
 }
}

sign_message_eip191은 기본적으로 sign_message와 동일하게 Klip 사용자의 계정 키로 메시지를 서명하는 역할을 수행하나, sign_message는 Klaytn의 표준에 따라 "\x19Klaytn Signed Message:\n" + len(message)의 접두사를 붙이고, sign_message_eip191은 Kaia의 표준에 따라 "\x19Ethereum Signed Message:\n" + len(message)의 접두사를 붙인다는 차이점이 있습니다. Kaia에서 변경된 메시지 서명 표준의 변화에 대해서는 여기를 참고하시기 바랍니다. from은 Klip 사용자의 주소입니다. Klip 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다. 선택 항목이므로 생략할 수 있습니다. is_hex_encoded는 메시지 원문의 데이터 타입입니다. true 일 경우 서명 값을 데이터의 hex encoding 된 byte 배열로 판단하여 서명합니다. 생략하거나 false 일 경우는 문자열로 판단합니다. value는 서명할 메시지의 원문입니다. is_hex_encoded 가 true 일 경우 0x 로 시작하는 hex encoding된 byte 배열이여야 합니다.

Request Example

curl -X POST "https://a2a-api.klipwallet.com/v2/a2a/prepare" \
-d '{"bapp": { "name" : "My BApp" }, "chain": "klaytn", "type": "execute_contract" }' \
-H "Content-Type: application/json"

Response Details

명칭	형식	설명
request_key	string	요청을 유니크하게 구분한 키값입니다. Request, Result API 호출 시 사용합니다.
status	string	API 요청의 현재 상태입니다. 기본적으로 prepared 상태가 됩니다.
expiration_time	number	request key 만료 시간을 unix timestamp로 표현한 값입니다.
estimated_gas	number	트랜잭션을 발생시키는 요청이면서 from 값이 존재할 경우 실제 트랜잭션 생성에 사용될 gasLimit 값입니다.
Error	object	트랜잭션이 실패(revert)할 가능성이 있거나 execute_contract 요청에서 params 값이 적절하지 않은 경우 에러를 반환합니다. 1. revert from 주소와 함께 요청 시 트랜잭션을 검증하여 revert 메시지를 반환합니다. 되돌아갈 가능성이 있기 때문에 트랜잭션을 생성하지 않습니다. 해당 오브젝트는 code와 message를 반환하며 revert 상황일 때 값은 다음과 같습니다. message는 트랜잭션이 되돌아가는 원인을 string으로 포함합니다. "error":{"code":6414,"message":(revert 원인)} 2. params error params는 abi의 타입에 맞는 데이터를 입력해야 합니다. address type에 숫자(222)를 넣을 경우 다음처럼 에러를 반환 합니다. 필드명을 함께 반환하기 때문에 어떤 param이 잘못 입력되었는지 찾는데 도움을 줍니다. "error":{"code":6408,"message":"dummy_arg_name: [(json.Number)222] is not (address)"}

status는 prepared, requested, completed, canceled, error 상태중 하나를 가집니다. canceled 상태는 사용자가 명시적으로 App2App 진행을 취소했을 때 설정됩니다.

자세한 내용은 튜토리얼을 확인하십시오.

Request

DEEP LINK https://klipwallet.com?target=/a2a?request_key=

Klip에 인증 또는 서명을 요청하기 위한 예제는 아래 Request Example 항목을 참조하십시오.

Query Parameters

Name	Type	Description
request_key*	string	Prepare 단계에서 얻은 request key를 전달하십시오. request_key를 통해서 요청을 구분할 수 있습니다.

200

Request Example

아래 예제에서 request_key 필드는 Prepare 스텝에서 얻은 값으로 설정합니다.

iOS 또는 Android 환경

https://klipwallet.com/?target=/a2a?request_key=9892...4aeb

위 Deep Link를 통해 클립 앱을 실행하거나 설치할 수 있도록 유도됩니다.

PC 또는 이기종 디바이스 환경 (QR code)

아래와 같은 URL 형식으로 QR code를 생성합니다. 사용자는 클립 앱 또는 네이티브 카메라앱를 통해 QR code를 인식하여 App2App 요청을 처리할 수 있습니다.

https://klipwallet.com/?target=/a2a?request_key=9892...4aeb

QR code 샘플

QR code 생성을 위해서 개발 환경별로 아래 오픈소스 프로젝트를 참고하실 수 있습니다.

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

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

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

Result

GET https://a2a-api.klipwallet.com/v2/a2a/result?request_key=

App2App API 요청에 대한 결과를 확인합니다.

Query Parameters

Name	Type	Description
request_key*	string	Prepare 단계에서 얻은 request key를 전달하십시오. request_key를 통해서 요청을 구분할 수 있습니다.

200

{
  "request_key": "random key",
  "expiration_time": unix timestamp,
  "status": "requested" or "completed",
  "result": {
    "klaytn_address": string // 호환성을 위해 필드명에는 klaytn을 사용하나 Kaia를 포함한 모든 네트워크에 동일한 주소를 갖습니다.
  }
}

400

500

Request Example

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

{
  "request_key": "random key",
  "expiration_time": unix timestamp,
  "status": "completed",
}

명칭	형식	설명
request_key	string	요청 키값입니다.
expiration_time	number	request key 만료 시간을 unix timestamp로 표현한 값입니다.
status	string	API 요청의 현재 상태입니다. 처리가 완료되었다면 completed 상태가 리턴됩니다.

status는 prepared, requested, completed, canceled, error 상태중 하나를 가집니다. canceled 상태는 사용자가 명시적으로 App2App 진행을 취소했을 때 설정됩니다.

2. type: send_klay, send_token, send_card, execute_contract

{
  "request_key": "random key",
  "expiration_time": unix timestamp,
  "status": "completed",
  "result": {
    "tx_hash": string,
    "status": "success"
  }
}

명칭	형식	설명
request_key	string	요청 키값입니다.
expiration_time	number	request key 만료 시간을 unix timestamp로 표현한 값입니다.
status	string	API 요청의 현재 상태입니다. 처리가 완료되었다면 completed 상태가 리턴됩니다.
result	object	서명 요청의 결과입니다. transaction hash와 해당 transaction의 처리 상태가 리턴됩니다.

result object의 status 필드는 pending 상태의 경우, 사용자가 Klip에서 확인했자만, 체인에서 아직 트랜잭션을 처리하는 중임을 의미합니다. 일반적으로 몇 초후에 다시 확인하면 요청를 확인할 수 있습니다. 그리고 success는 요청이 성공적으로 처리됐을 때, fail은 요청이 실패했을 때의 상태를 나타냅니다.

3. type: sign_message, sign_message_eip191

{
 "request_key": "random key",
 "expiration_time": unix timestamp,
 "status": "completed",
 "result": {
    "signature": string // 원문에 대한 사용자 서명
    "hash": string
 } 
}

명칭	형식	설명
request_key	string	요청 키 값입니다.
expiration_time	number	request key 만료 시간을 unix timestamp로 표현한 값입니다.
status	string	API 요청 상태입니다. 처리가 완료되었다면 completed를 반환합니다.
signature	string	서명 요청의 결과입니다. 원문에 대한 서명이 전달 됩니다. 서명의 v 값은 27 혹은 28입니다. 요청 type이 sign_message인 경우에는 "\x19Klaytn Signed Message:\n" + len(message)의 접두사를 붙이고, sign_message_eip191은 "\x19Ethereum Signed Message:\n" + len(message)의 접두사를 붙여 서명합니다.
hash	string	원문에 대해 각 체인에서 미리 정해진 데이터를 붙여 해싱한 값입니다. 실제로 서명에 사용되는 데이터입니다.

result 오브젝트의 signature 필드는 요청된 원문에 서명한 결과입니다. status는 prepared, requested, completed, canceled, error 상태 중 하나를 결과값으로 표시합니다. canceled는 사용자가 명시적으로 App2App 진행을 취소했을 때 반환됩니다.

자세한 내용은 튜토리얼을 확인하십시오.

Get Card Information

GET https://a2a-api.klipwallet.com/v2/a2a/cards?cursor=

사용자 EOA와 NFT 컨트랙트 주소를 입력하고, 이 사용자가 소유한 카드 중에서 이 NFT 컨트랙트에서 발행한 카드 목록을 반환합니다.

Query Parameters

Name	Type	Description
chain	string	소유 정보를 조회할 체인명입니다. (klaytn, ethereum, polygon)
sca*	string	소유 정보를 조회할 smart contract address입니다.
eoa*	string	어떤 사용자 EOA의 카드 소유 정보를 얻어올지 특정합니다. 일반적으로 App2App auth 요청을 통해 얻은 EOA를 인자로 사용합니다.
cursor	string	카드 보유량이 100개 이상이면 다음 100개 정보를 받는 커서값입니다.

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

400

500

Request Example

curl -X GET "https://a2a-api.klipwallet.com/v2/a2a/cards?chain=klaytn&sca=0x1234...&eoa=0x9876...&cursor=mrzedXOE9OeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL" \
-H "Content-Type: application/json"

Response Details

명칭	형식	설명
name	string	이 Contract 이름입니다.
symbol_img	string	이 Contract symbol image URL입니다.
cards	array	각 카드 정보를 담은 object 배열입니다.
next_cursor	string	카드 결과값이 100개 이상이면 다음 100개 정보를 불러올 커서값입니다.

Response Details for cards[i]

명칭	형식	설명
created_at	number	카드가 발행된 시간입니다.
updated_at	number	카드가 업데이트된 시간입니다.
owner	string	이 계정 EOA 주소입니다.
sender	string	이 계정으로 카드를 보낸 사람의 EOA 주소입니다.
card_id	number	카드 ID입니다.
card_uri	string	카드 메타데이터가 담긴 JSON 파일 URL입니다.
transaction_hash	string	카드를 발행한 스마트 컨트랙트 트랜잭션 해시입니다.

자세한 내용은 튜토리얼을 확인하십시오.

이 문서 혹은 Klip에 관한 문의는 개발자 포럼을 방문해 도움을 받으십시오.