Klip Docs
Search…
⌃K

App2App

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

※ 개요

App2App API를 사용하는 단계는 Prepare, Request, Result 3단계로 구분됩니다.
  • Klip API를 사용함에 있어 사용자는 (주)그라운드엑스를 사칭해서는 안됩니다.
  • Klip API 사용에 따라 발생하는 모든 책임은 전적으로 사용자에게 있으며, (주)그라운드엑스는 사용자 또는 제3자에 대해 어떠한 책임도 지지 않습니다.
  • Klip API 사용자가 과도한 네트워크 트래픽을 발생시키는 시도하는 등 불법 혹은 비정상적인 방식으로 API를 사용하려고 시도하는 경우, 사전 고지없이 API 사용이 차단될 수 있습니다.

Prepare

BApp에서 어떤 작업을 실행하고 싶은지 정의하는 단계입니다. "인증"을 제외한 나머지는 Klaytn에 트랜잭션을 전송하는 작업입니다. 트랜잭션 전송을 위해 Prepare 단계에서는 트랜잭션 객체를 생성합니다. 실행 가능한 작업은 다음과 같습니다.
  • 인증
  • KLAY 전송
  • 토큰 전송
  • 카드 전송
  • 스마트 컨트랙트 실행
  • 메시지 서명

인증

BApp 회원의 Klip 지갑에 접근하기 위한 인증 작업입니다. BApp에서 Klip 사용자의 EOA를 얻어야할 때 사용합니다. 이 기능을 위한 Klip 로그인 버튼을 제공하는 경우, 버튼 스타일과 버튼명은 아래 가이드를 준수해야 합니다.
Klip 로그인 버튼 가이드
이 기능을 사용하는 경우, Klip 계정을 연결 해지하는 기능도 반드시 제공해야 하며 해지 시 수집한 사용자 EOA 정보를 즉시 삭제해야 합니다.
위와 같은 조건이 지켜지지 않을 경우, 사전 고지없이 API 사용이 차단될 수 있습니다.

KLAY 전송

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

토큰 전송

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

카드 전송

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

스마트 컨트랙트 실행

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

메시지 서명

Klip 계정으로 메시지를 서명하여 반환합니다.
Prepare API 호출에 성공하면 응답값으로 “인증키"(Request Key)를 받습니다. 인증키는 Prepare 단계에서 정의한 작업을 실제로 실행하도록 요청하는 "Request" 및 "Result" 단계에서 사용합니다.

Request

위 단계에서 정의한 작업을 실제로 실행하도록 요청합니다.
"인증"은 BApp 회원의 Klip 지갑 주소(EOA)를 BApp으로 받아오는 작업이며 그 외에 나머지 작업은 위 트랜잭션에 서명(Signature)를 받는 작업입니다. 이들 4가지 작업은 사실 Klaytn에 트랜잭션 전송을 요청하는 작업이며 토큰 전송, KLAY 전송, 카드 전송, 스마트 컨트랙트 실행 트랜잭션을 Klaytn에 전송합니다. 이 단계에서는 이들 트랜잭션에 Klaytn 계정 키로 서명(Signature)한 다음 Klaytn에 전송합니다.
인증 또는 서명은 Deep Link를 통해 Klip에 요청합니다.
예를 들어, BApp 회원 “A”가 다른 BApp 회원 “B”에게 토큰 또는 아이템을 전송하는 버튼을 클릭하면 여러분의 BApp은 App2App API를 사용해 “A”의 Klip 지갑 주소를 인증(생략 가능)하고 “A”의 Klip 지갑에 접근합니다. 그리고 전송하려는 토큰 또는 카드를 “B”의 Klaytn 계정 주소에 전송하는 트랜잭션을 보냅니다.

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 유저가 클릭했을 때 Klip 앱이 실행됩니다. request_key 필드에는 Prepare 과정에서 응답으로 전달받은 값을 사용합니다.
Klip 앱이 설치되지 않은 경우 카카오톡을 실행합니다. 카카오톡 또한 설치되지 않은 경우에는 App Store 내 Klip 앱 다운로드 화면으로 이동합니다.
https://klipwallet.com/?target=/a2a?request_key=9892...4aeb

※ API Specification

App2App API 세부 스펙은 아래와 같습니다.
post
https://a2a-api.klipwallet.com
/v2/a2a/prepare
Prepare
** bapp object 예시 **
{
"bapp": {
"name": "My BApp",
"callback": { // all optional
"success": "mybapp://.../success/...",
"fail": "mybapp://.../fail/..."
}
}
}
name은 인증 또는 서명 시 Klip 사용자 화면에 표시될 BApp의 이름입니다. callbacksuccess 필드는 Klip에서 사용자 확인이 성공적으로 처리됐을 때 BApp으로 돌아가기 위한 Deep Link입니다. fail은 반대로 실패한 경우 BApp으로 돌아가기 위한 Deep Link입니다. callback 객체는 optional입니다.
** transaction object 예시 **
  1. 1.
    type: send_klay
{
"transaction": {
"from": "0x8756...4321", // optional
"to": "0x1234...5678",
"amount": "100"
}
}
to는 KLAY를 전송받는 사람의 klaytn address입니다. amount를 받을 KLAY 양입니다. from은 Klip 사용자의 주소입니다. from은 optional 필드이고 Klip 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다.
  1. 1.
    type: send_token
{
"transaction": {
"contract": "SCA",
"from": "0x8756...4321", // optional
"to": "0x1234...5678",
"amount": "100",
}
}
contract는 토큰의 스마트 컨트랙트 주소입니다. to는 토큰을 전송받는 사람의 Klaytn 계정 주소입니다. amount를 받을 토큰 양입니다. 참고로, amount는 컨트랙트 내 decimal을 반영하여 자동으로 환산되는 수치입니다. 예를 들면, 18 decimal의 KIP-7 컨트랙트(FT 컨트랙트)에서 amount 1은 10^18 개의 최소 단위 토큰을 의미하게 됩니다. from은 Klip 사용자의 주소입니다. from은 optional 필드이고 Klip 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다.
  1. 1.
    type: send_card
{
"transaction": {
"contract": "0xA987...4321",
"from": "0x8756...4321", // optional
"to": "0x1234...5678",
"card_id": "100",
}
}
contract는 토큰의 스마트 컨트랙트 주소입니다. to는 카드를 전송받는 사람의 Klaytn 주소입니다. card_id는 전송할 카드의 고유번호입니다. from은 Klip 사용자의 주소입니다. from은 optional 필드이고 Klip 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다.
  1. 1.
    type: execute_contract
{
"transaction": {
"from": "0x8756...4321", // optional
"to": "0xA987...4321", // contract address
"value": "1000000000000000000", // 단위는 peb. 1 KLAY
"abi": "...",
"params": "...",
"encoded_function_call": "0x123...23fe23"
}
}
to는 실행할 스마트 컨트랙트 주소입니다. value는 해당 컨트랙트에 전송할 KLAY입니다. 단위는 peb입니다. 예를 들어, 1 KLAY는 1000000000000000000 peb입니다. abi는 실행할 컨트랙트 함수 정보입니다. params는 해당 함수에 넘겨줄 인자값입니다. 최신 버전 부터는 tuple 타입도 지원합니다. abiparam 대신에 encoded_function_call을 사용할 수 있습니다. encoded_function_call 에 tx의 data에 들어갈 정보를 입력해주면 해당 값을 사용하여 tx를 실행합니다. abi, param 혹은 encoded_function_call 중 하나만을 사용하여 tx를 실행하기 때문에 사용하지 않는 값은 비워져 있어야 합니다. from은 Klip 사용자의 주소입니다. from은 optional 필드이고 Klip 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다. abiparams 의 구체적인 예시는 튜토리얼을 참조하십시오.
from은 optional 필드이지만 트랜잭션 처리 시 원래 의도했던 Klip 사용자가 맞는지 검증하는 용도로 사용되므로 가능하면 설정하는 것을 권장합니다.
** message object 예시 **
  1. 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 배열이여야 합니다.
Request Example
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
명칭
형식
설명
request_key
string
요청을 유니크하게 구분한 키값입니다. Request, Result API 호출 시 사용합니다.
status
string
API 요청의 현재 상태입니다. 기본적으로 prepared 상태가 됩니다.
expiration_time
number
request key 만료 시간을 unix timestamp로 표현한 값입니다.
Error
object
트랜잭션을 되돌릴(revert) 가능성이 있을 경우에만 반환합니다. from 주소와 함께 요청 시 트랜잭션을 검증하여 revert 메시지를 반환합니다. 되돌아갈 가능성이 있기 때문에 트랜잭션을 생성하지 않습니다. 해당 오브젝트는 code와 message를 반환하며 revert 상황일 때 값은 다음과 같습니다. message는 트랜잭션이 되돌아가는 원인을 string으로 포함합니다. "error":{"code":6414,"message":(revert 원인)}
statusprepared, requested, completed, canceled, error 상태중 하나를 가집니다. canceled 상태는 사용자가 명시적으로 App2App 진행을 취소했을 때 설정됩니다.
자세한 내용은 튜토리얼을 확인하십시오. 이 문서 혹은 Klip에 관한 문의는 개발자 포럼을 방문해 도움을 받으십시오.
deep link
https://klipwallet.com/?target=/a2a?
request_key=
Request
Request Example
아래 예제에서 request_key 필드는 Prepare 스텝에서 얻은 값으로 설정합니다.
https://klipwallet.com/?target=/a2a?request_key=9892...4aeb
Klip 앱이 설치되지 않은 경우 카카오톡을 실행합니다. 카카오톡 또한 설치되지 않은 경우에는 App Store 내 Klip 앱 다운로드 화면으로 이동합니다.

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

아래와 같은 URL 형식으로 QR code를 생성합니다. 사용자는 Klip 또는 네이티브 카메라앱를 통해 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
get
https://a2a-api.klipwallet.com
/v2/a2a/result?request_key=
Result
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. 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 상태가 리턴됩니다.
statusprepared, requested, completed, canceled, error 상태중 하나를 가집니다. canceled 상태는 사용자가 명시적으로 App2App 진행을 취소했을 때 설정됩니다.
  1. 1.
    type: sign_message
{
"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입니다.
hash
string
원문에 대해 klaytn에서 미리 정해진 데이터를 붙여 해싱한 값입니다. 실제로 서명에 사용되는 데이터입니다. 다음을 참조하세요. https://ko.docs.klaytn.foundation/dapp/sdk/caver-js/v1.4.1/api-references/caver.klay.accounts#sign
result 오브젝트의 signature 필드는 요청된 원문에 서명한 결과입니다. status는 prepared, requested, completed, canceled, error 상태 중 하나를 결과값으로 표시합니다. canceled는 사용자가 명시적으로 App2App 진행을 취소했을 때 반환됩니다.
  1. 1.
    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에서 확인했자만, Klaytn에서 아직 트랜잭션을 처리하는 중임을 의미합니다. 일반적으로 몇 초후에 다시 확인하면 요청를 확인할 수 있습니다. 그리고 success는 요청이 성공적으로 처리됐을 때, fail은 요청이 실패했을 때의 상태를 나타냅니다.
자세한 내용은 튜토리얼을 확인하십시오. 이 문서 혹은 Klip에 관한 문의는 개발자 포럼을 방문해 도움을 받으십시오.
get
https://a2a-api.klipwallet.com
/v2/a2a/cards?cursor=
Get Card Information
Request Example
curl -X GET "https://a2a-api.klipwallet.com/v2/a2a/cards?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에 관한 문의는 개발자 포럼을 방문해 도움을 받으십시오.