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 버튼 템플릿 다운로드
이 기능을 사용하는 경우, 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 처리를 위한 대략적인 흐름은 아래 그림과 같습니다.
API 요청과 별개로 카드 정보 조회는 일반적인 REST API 호출 흐름과 동일합니다. Klip 거치지 않고 Backend에 요청하여 정보를 받아옵니다. 흐름은 아래와 같습니다.
Deep Link는 아래와 같은 형태의 링크이고, BApp 유저가 클릭했을 때 클립 앱을 실행하거나 설치할 수 있도록 유도됩니다. request_key
필드에는 Prepare 과정에서 응답으로 전달받은 값을 사용합니다.
※ API Specification
App2App API 세부 스펙은 아래와 같습니다.
Prepare
POST
https://a2a-api.klipwallet.com/v2/a2a/prepare
App2App API 요청 처리를 준비하고 request key를 발급합니다.
Headers
Content-Type*
string
application/json
Request Body
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
타입인 경우 이 필드를 필수적으로 기입해야 합니다. 그 외의 타입에서는 설정하지 않습니다. 아래 예시를 참고하십시오.
bapp
object 예시
bapp
object 예시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 예시
transaction
object 예시1. type: send_token
send_token
contract
는 토큰의 스마트 컨트랙트 주소입니다 (네이티브 코인의 경우 0x0000000000000000000000000000000000000000
입력). to
는 토큰을 전송받는 사람의 계정 주소입니다. amount
를 받을 토큰 양입니다. 참고로, amount
는 컨트랙트 내 decimal을 반영하여 자동으로 환산되는 수치입니다. 예를 들면, 18 decimal의 FT 컨트랙트에서 amount
1은 10^18 개의 최소 단위 토큰을 의미하게 됩니다. from
은 Klip 사용자의 주소입니다. from
은 optional 필드이고 Klip 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다.
2. type: send_card
send_card
contract
는 NFT의 스마트 컨트랙트 주소입니다. to
는 카드를 전송받는 사람의 주소입니다. card_id
는 전송할 카드의 고유번호입니다. from
은 Klip 사용자의 주소입니다. from
은 optional 필드이고 Klip 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다.
3. type: execute_contract
execute_contract
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 예시
message
object 예시1. type: sign_message
sign_message
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
sign_message_eip191
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
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
request_key*
string
Prepare 단계에서 얻은 request key를 전달하십시오. request_key
를 통해서 요청을 구분할 수 있습니다.
Request Example
아래 예제에서 request_key
필드는 Prepare 스텝에서 얻은 값으로 설정합니다.
iOS 또는 Android 환경
위 Deep Link를 통해 클립 앱을 실행하거나 설치할 수 있도록 유도됩니다.
PC 또는 이기종 디바이스 환경 (QR code)
아래와 같은 URL 형식으로 QR code를 생성합니다. 사용자는 클립 앱 또는 네이티브 카메라앱를 통해 QR code를 인식하여 App2App 요청을 처리할 수 있습니다.
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
request_key*
string
Prepare 단계에서 얻은 request key를 전달하십시오. request_key
를 통해서 요청을 구분할 수 있습니다.
Request Example
Response Details
1. type: auth
auth
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
send_klay
, send_token
, send_card
, execute_contract
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
sign_message
, sign_message_eip191
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
chain
string
소유 정보를 조회할 체인명입니다. (klaytn
, ethereum
, polygon
)
sca*
string
소유 정보를 조회할 smart contract address입니다.
eoa*
string
어떤 사용자 EOA의 카드 소유 정보를 얻어올지 특정합니다. 일반적으로 App2App auth
요청을 통해 얻은 EOA를 인자로 사용합니다.
cursor
string
카드 보유량이 100개 이상이면 다음 100개 정보를 받는 커서값입니다.
Request Example
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
sender
string
card_id
number
카드 ID입니다.
card_uri
string
카드 메타데이터가 담긴 JSON 파일 URL입니다.
transaction_hash
string
카드를 발행한 스마트 컨트랙트 트랜잭션 해시입니다.
자세한 내용은 튜토리얼을 확인하십시오.
이 문서 혹은 Klip에 관한 문의는 개발자 포럼을 방문해 도움을 받으십시오.
Last updated