App2App
이 페이지에서는 BApp에서 Klip을 활용하기 위한 App2App REST API를 설명합니다.
App2App API를 사용하는 단계는 Prepare, Request, Result 3단계로 구분됩니다.
- Klip API를 사용함에 있어 사용자는 (주)그라운드엑스를 사칭해서는 안됩니다.
- Klip API 사용에 따라 발생하는 모든 책임은 전적으로 사용자에게 있으며, (주)그라운드엑스는 사용자 또는 제3자에 대해 어떠한 책임도 지지 않습니다.
- Klip API 사용자가 과도한 네트워크 트래픽을 발생시키는 시도하는 등 불법 혹은 비정상적인 방식으로 API를 사용하려고 시도하는 경우, 사전 고지없이 API 사용이 차단될 수 있습니다.
BApp에서 어떤 작업을 실행하고 싶은지 정의하는 단계입니다. "인증"을 제외한 나머지는 체인에 트랜잭션을 전송하는 작업입니다. 트랜잭션 전송을 위해 Prepare 단계에서는 트랜잭션 객체를 생성합니다. 실행 가능한 작업은 다음과 같습니다.
- 인증
- 토큰 전송
- 카드 전송
- 스마트 컨트랙트 실행
- 메시지 서명
BApp 회원의 Klip 지갑에 접근하기 위한 인증 작업입니다. BApp에서 Klip 사용자의 EOA를 얻어야할 때 사용합니다. 이 기능을 위한 Klip 로그인 버튼을 제공하는 경우, 버튼 스타일과 버튼명은 아래 가이드를 준수해야 합니다.
Klip 로그인 버튼 가이드
이 기능을 사용하는 경우, Klip 계정을 연결 해지하는 기능도 반드시 제공해야 하며 해지 시 수집한 사용자 EOA 정보를 즉시 삭제해야 합니다.
위와 같은 조건이 지켜지지 않을 경우, 사전 고지없이 API 사용이 차단될 수 있습니다.
BApp 회원의 Klip 지갑에서 다른 계정 주소(EOA)로 토큰(Fungible Token)을 전송하는 작업입니다. 토큰 전송을 위한 트랜잭션 객체를 생성합니다. 컨트랙트 주소에
0x0000000000000000000000000000000000000000 값을 입력하면 네이티브 코인 (KLAY, ETH, MATIC 등) 전송이 가능합니다.BApp 회원의 Klip 지갑에서 다른 계정 주소(EOA)로 카드(Non-Fungible Token)을 전송하는 작업입니다. 카드 전송을 위한 트랜잭션 객체를 생성합니다.
Klip 계정으로 스마트 컨트랙트를 실행하는 작업입니다. 컨트랙트 실행을 위한 트랜잭션 객체를 생성합니다.
Klip 계정으로 메시지를 서명하여 반환합니다.
Prepare API 호 출에 성공하면 응답값으로 “인증키"(Request Key)를 받습니다.
인증키는 Prepare 단계에서 정의한 작업을 실제로 실행하도록 요청하는 "Request" 및 "Result" 단계에서 사용합니다.
위 단계에서 정의한 작업을 실제로 실행하도록 요청합니다.
"인증"은 BApp 회원의 Klip 지갑 주소(EOA)를 BApp으로 받아오는 작업이며 그 외에 나머지 작업은 위 트랜잭션에 서명(Signature)를 받는 작업입니다. 이들 4가지 작업은 사실 체인에 트랜잭션 전송을 요청하는 작업이며 토큰 전송, KLAY 전송, 카드 전송, 스마트 컨트랙트 실행 트랜잭션을 체인에 전송합니다. 이 단계에서는 이들 트랜잭션에 계정 키로 서명(Signature)한 다음 체인에 전송합니다.
인증 또는 서명은 Deep Link를 통해 Klip에 요청합니다.
예를 들어, BApp 회원 “A”가 다른 BApp 회원 “B”에게 토큰 또는 아이템을 전송하는 버튼을 클릭하면 여러분의 BApp은 App2App API를 사용해 “A”의 Klip 지갑 주소를 인증(생략 가능)하고 “A”의 Klip 지갑에 접근합니다. 그리고 전송하려는 토큰 또는 카드를 “B”의 계정 주소에 전송하는 트랜잭션을 보냅니다.
마지막으로 Result 단계는 Request 단계에서 요청한 작업을 실행했을 때 결과 또는 응답값을 얻는 단계입니다.
API는 형태에 따라서 두 가지로 구분할 수 있습니다. 먼저 Prepare와 Result 스텝은 Klip Backend 서버로 요청을 날리는 REST API 형태이고, Request 스텝은 Klip을 띄워서 처리하기 위한 Deep Link 형태입니다. 앞선 두 가지와 별개로 필요 시 사용자의 카드 소유 정보를 얻기위한 REST API 형태의 요청이 있습니다.
App2App 처리를 위한 대략적인 흐름은 아래 그림과 같습니다.
App2App Flow
API 요청과 별개로 카드 정보 조회는 일반적인 REST API 호출 흐름과 동일합니다. Klip 거치지 않고 Backend에 요청하여 정보를 받아옵니다. 흐름은 아래와 같습니다.
App2App Information API Flow
Deep Link는 아래와 같은 형태의 링크이고, BApp 유저가 클릭했을 때 카카오톡 Klip이 실행됩니다.
request_key 필드에는 Prepare 과정에서 응답으로 전달받은 값을 사용합니다.kakaotalk://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=9892...4aeb
App2App API 세부 스펙은 아래와 같습니다.
post
https://a2a-api.klipwallet.com
/v2/a2a/prepare
Prepare
{
"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": {
"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 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다.{
"transaction": {
"contract": "0xA987...4321",
"from": "0x8756...4321", // optional
"to": "0x1234...5678",
"card_id": "100",
}
}
contract는 토큰의 스마트 컨트랙트 주소입니다. to는 카드를 전송받는 사람의 주소입니다. card_id는 전송할 카드의 고유번호입니다. from은 Klip 사용자의 주소입니다. from은 optional 필드이고 Klip 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다.{
"transaction": {
"from": "0x8756...4321", // optional
"to": "0xA987...4321", // contract address
"value": "1000000000000000000", // 단위는 실제 트랜잭션의 value 단위와 동일
"abi": "...",
"params": "...",
"encoded_function_call": "0x123...23fe23"
}
}
to는 실 행할 스마트 컨트랙트 주소입니다. value는 해당 컨트랙트에 전송할 코인입니다. value의 단위는 실제 해당 체인의 트랜잭션 생성 인자와 동일합니다. Klaytn 기준으로 단위는 peb이며, 1 KLAY는 1000000000000000000 (10^18) peb입니다. 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": {
"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" }, "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 진행을 취소했을 때 설정됩니다.deep link
kakaotalk://klipwallet/open?url=https://klipwallet.com/?target=/a2a?
request_key=
Request
Request Example
아래 예제에서
request_key 필드는 Prepare 스텝에서 얻은 값으로 설정합니다.kakaotalk://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=9892...4aeb
카카오톡 Klip을 실행합니다. 카카오톡이 설치되지 않은 경우에 Deep Link가 정상적으로 동작하지 않을 수도 있습니다.
아래와 같은 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
{
"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 진행을 취소했을 때 설정됩니다.{
"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 | 원문에 대해 각 체인에서 미리 정해진 데이터를 붙여 해싱한 값입니다. 실제로 서명에 사용되는 데이터입니다. |
result 오브젝트의 signature 필드는 요청된 원문에 서명한 결과입니다. status는 prepared, requested, completed, canceled, error 상태 중 하나를 결과값으로 표시합니다. canceled는 사용자가 명시적으로 App2App 진행을 취소했을 때 반환됩니다.{
"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은 요청이 실패했을 때의 상태를 나타냅니다.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?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]Last modified 2mo ago