Klip Docs
Search…
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 계정으로 스마트 컨트랙트를 실행하는 작업입니다. 컨트랙트 실행을 위한 트랜잭션 객체를 생성합니다.
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는 iOS에서는 URL Scheme을 사용하고 Android 환경에서는 intentURI를 사용합니다. 먼저 URL Scheme은 아래와 같은 형태의 링크이고, BApp 유저가 클릭했을 때 카카오톡 더보기 탭의 Klip이 실행됩니다. request_key 필드에는 Prepare 과정에서 응답으로 전달받은 값을 사용합니다.
1
kakaotalk://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=9892...4aeb
Copied!
Android 환경을 위한 IntentURI은 아래와 형태입니다.
1
intent://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=9892...4aeb#Intent;scheme=kakaotalk;package=com.kakao.talk;end
Copied!

※ API Specification

App2App API 세부 스펙은 아래와 같습니다.
post
https://a2a-api.klipwallet.com
/v2/a2a/prepare
Prepare
** bapp object 예시 **
1
{
2
"bapp": {
3
"name": "My BApp",
4
"callback": { // all optional
5
"success": "mybapp://.../success/...",
6
"fail": "mybapp://.../fail/..."
7
}
8
}
9
}
Copied!
name은 인증 또는 서명 시 Klip 사용자 화면에 표시될 BApp의 이름입니다. callbacksuccess 필드는 Klip에서 사용자 확인이 성공적으로 처리됐을 때 BApp으로 돌아가기 위한 Deep Link입니다. fail은 반대로 실패한 경우 BApp으로 돌아가기 위한 Deep Link입니다. callback 객체는 optional입니다.
** transaction object 예시 **
  1. 1.
    type: send_klay
1
{
2
"transaction": {
3
"from": "0x8756...4321", // optional
4
"to": "0x1234...5678",
5
"amount": "100"
6
}
7
}
Copied!
to는 KLAY를 전송받는 사람의 klaytn address입니다. amount를 받을 KLAY 양입니다. from은 Klip 사용자의 주소입니다. from은 optional 필드이고 Klip 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다.
  1. 1.
    type: send_token
1
{
2
"transaction": {
3
"contract": "SCA",
4
"from": "0x8756...4321", // optional
5
"to": "0x1234...5678",
6
"amount": "100",
7
}
8
}
Copied!
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
1
{
2
"transaction": {
3
"contract": "0xA987...4321",
4
"from": "0x8756...4321", // optional
5
"to": "0x1234...5678",
6
"card_id": "100",
7
}
8
}
Copied!
contract는 토큰의 스마트 컨트랙트 주소입니다. to는 카드를 전송받는 사람의 Klaytn 주소입니다. card_id는 전송할 카드의 고유번호입니다. from은 Klip 사용자의 주소입니다. from은 optional 필드이고 Klip 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다.
  1. 1.
    type: execute_contract
1
{
2
"transaction": {
3
"from": "0x8756...4321", // optional
4
"to": "0xA987...4321", // contract address
5
"value": "1000000000000000000", // 단위는 peb. 1 KLAY
6
"abi": "...",
7
"params": "..."
8
}
9
}
Copied!
to는 실행할 스마트 컨트랙트 주소입니다. value는 해당 컨트랙트에 전송할 KLAY입니다. 단위는 peb입니다. 예를 들어, 1 KLAY는 1000000000000000000 peb입니다. abi는 실행할 컨트랙트 함수 정보입니다. params는 해당 함수에 넘겨줄 인자값입니다. from은 Klip 사용자의 주소입니다. from은 optional 필드이고 Klip 사용자의 실제 주소와 비교하여 의도하지 않은 요청을 검사하는 용도로 사용됩니다. abiparams의 구체적인 예시는 튜토리얼을 참조하십시오.
from은 optional 필드이지만 트랜잭션 처리 시 원래 의도했던 Klip 사용자가 맞는지 검증하는 용도로 사용되므로 가능하면 설정하는 것을 권장합니다.
Request Example
1
curl -X POST "https://a2a-api.klipwallet.com/v2/a2a/prepare" \
2
-d '{"bapp": { "name" : "My BApp" }, "type": "execute_contract" }' \
3
-H "Content-Type: application/json"
Copied!
Response Details
명칭
형식
설명
request_key
string
요청을 유니크하게 구분한 키값입니다. Request, Result API 호출 시 사용합니다.
status
string
API 요청의 현재 상태입니다. 기본적으로 prepared 상태가 됩니다.
expiration_time
number
request key 만료 시간을 unix timestamp로 표현한 값입니다.
statusprepared, requested, completed, canceled, error 상태중 하나를 가집니다. canceled 상태는 사용자가 명시적으로 App2App 진행을 취소했을 때 설정됩니다.
자세한 내용은 튜토리얼을 확인하십시오. 이 문서 혹은 Klip에 관한 문의는 개발자 포럼을 방문해 도움을 받으십시오.
deep link
kakaotalk://klipwallet/open?url=https://klipwallet.com/?target=/a2a?
request_key=
Request
Request Example
아래 예제에서 request_key 필드는 Prepare 스텝에서 얻은 값으로 설정합니다.

iOS

1
kakaotalk://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=9892...4aeb
Copied!

Android

1
intent://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=9892...4aeb#Intent;scheme=kakaotalk;package=com.kakao.talk;end
Copied!

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

아래와 같은 URL 형식으로 QR code를 생성합니다. 사용자는 Klip 또는 네이티브 카메라앱를 통해 QR code를 인식하여 App2App 요청을 처리할 수 있습니다.
1
https://klipwallet.com/?target=/a2a?request_key=9892...4aeb
Copied!
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
1
curl -X GET "https://a2a-api.klipwallet.com/v2/a2a/result?request_key=9892...4aeb" \
2
-H "Content-Type: application/json"
Copied!
Response Details
  1. 1.
    type: auth
1
{
2
"request_key": "random key",
3
"expiration_time": unix timestamp,
4
"status": "completed",
5
}
Copied!
명칭
형식
설명
request_key
string
요청 키값입니다.
expiration_time
number
request key 만료 시간을 unix timestamp로 표현한 값입니다.
status
string
API 요청의 현재 상태입니다. 처리가 완료되었다면 completed 상태가 리턴됩니다.
statusprepared, requested, completed, canceled, error 상태중 하나를 가집니다. canceled 상태는 사용자가 명시적으로 App2App 진행을 취소했을 때 설정됩니다.
  1. 1.
    type: auth 이외의 타입
1
{
2
"request_key": "random key",
3
"expiration_time": unix timestamp,
4
"status": "completed",
5
"result": {
6
"tx_hash": string,
7
"status": "success"
8
}
9
}
Copied!
명칭
형식
설명
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
1
curl -X GET "https://a2a-api.klipwallet.com/v2/a2a/cards?sca=0x1234...&eoa=0x9876...&cursor=mrzedXOE9OeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL" \
2
-H "Content-Type: application/json"
Copied!
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에 관한 문의는 개발자 포럼을 방문해 도움을 받으십시오.
Last modified 21h ago