Klip

Klip은 사용자의 디지털 자산을 쉽고 편리하게 관리해 주는 개인 디지털 지갑 서비스입니다. 지금까지 다양한 블록체인 지갑이 있었지만, 어려운 사용자 경험으로 인해 제한적으로 활용되었습니다. Klip은 카카오 계정과 연동되어 메신저만큼 쉬운 사용자 경험을 제공합니다. 또한, Kaia 기반의 다양한 블록체인 서비스들을 소개하는 창구 기능을 하며 블록체인 서비스 확산에 기여합니다.

BApp과 카드

BApp(Blockchain Application)은 DApp(Decentralized Application)과 유사하지만, DApp과 달리 탈중앙화를 넘어 블록체인의 다른 많은 장점까지 흡수한 더 포괄적인 개념으로 사용된 용어입니다. DApp 개발에 관한 자세한 내용은 를 확인하시기 바랍니다.

카드란 Klip에서 사용되는 디지털 자산으로, 일반적으로 NFT를 가리킵니다. Klip 파트너사는 자산(게임 아이템, 할인 쿠폰 등)을 카드 형태로 발행하고 Klip 사용자 또는 BApp 사용자에게 보낼 수 있습니다. 사용자는 카드를 받고 Klip 지갑에서 원하는 카드를 사용하거나 또 다른 사람에게 보낼 수 있습니다. 이 과정에서 Klip 파트너사는 자신의 BApp을 잠재 고객에게 알리고 이들을 구매 고객으로 전환할 수 있습니다.

모든 카드는 기본적으로 (Non-Fungible Token)입니다. 대체 불가능한 토큰은 간단하게 말하면 "화폐"(비트코인, 이더리움 등)가 아닌 "고유한 자산"입니다. 5만원권 지폐 1장은 다른 5만원권 지폐 1장으로 완벽히 대체 가능합니다. 하지만, 내 예술 작품은 다른 이의 예술 작품으로 대체 불가능합니다. 다른 이의 명작이 주는 가치와 내 명작이 주는 가치가 서로 같지 않고 비교하기도 어렵기 때문입니다. 이렇게 수집품, 예술 작품, 개인용 물품 등 고유한 자산을 디지털화하여 블록체인상에 토큰 형태로 표현한 것이 바로 대체 불가 토큰입니다. 카드는 BApp에서 사용하는 대체 불가 토큰이며 Klip 사용자는 Klip에서 카드를 쓰고 교환합니다.

Klip API

Klip API는 외부 서비스에서 API를 통해 Klip에 있는 코인 및 대체 가능한 토큰(FT)을 전송하거나 Klip에서 카드(NFT)를 발행, 조회, 전송 또는 삭제하는 기능을 제공합니다. Klip API는 Klip Partners API와 App2App API로 구성됩니다. Klip은 Kaia 외에 Ethereum, Polygon 자산에 대해서도 동일한 기능을 제공합니다.

Klip Partners API

Klip Partners API는 서비스에 가입한 파트너사에서 직접 카드를 발행, 조회, 전송, 삭제하기 위한 API입니다. 복잡한 스마트 컨트랙트 배포나 관리 및 운영없이 간단한 API를 사용하여 카드를 활용하는 BApp을 개발할 수 있습니다. Klip Partners API를 사용하기 위한 절차는 아래와 같습니다.

1. Klip Partners에 가입 신청을 합니다.

2. Klip 운영진과 별도 협의를 거쳐 가입 승인을 얻은 후 으로 사이트에 로그인합니다.

3. 로그인 후, 로 카드 이미지로 쓸 이미지 파일을 업로드합니다.

4. 또는 로 업로드한 이미지를 사용해 카드를 직접 발행합니다.

또한 API를 통해서 계정 및 카드를 쉽게 관리할 수 있습니다.

• 으로 로그인한 후

  • 로 계정 비밀번호를 변경합니다.

  • 으로 핀 번호를 변경합니다.

  • 로 카드 정보를 조회하고 카드를 삭제합니다.

App2App API

App2App API는 BApp 개발자가 별도 가입 절차없이 Klip 사용자를 인증하고 해당 사용자의 토큰 및 카드를 전송하기 위한 API입니다. 또한 직접 개발한 스마트 컨트랙트 실행을 Klip 사용자에게 요청할 수 있습니다. 기본적으로 Klip 앱이 설치된 모바일 환경에서 BApp이 Deep Link를 통해 Klip에 서명을 요청하는 방식으로 동작합니다.

App2App API는 아래와 같은 상황에서 활용할 수 있습니다.

• BApp 사용자의 Klip 지갑 주소 인증

• Klip을 통한 KAIA, 토큰 전송

• Klip을 통한 카드 조회 및 전송

• Klip을 통한 Smart Contract 실행

App2App API를 사용하기 위한 절차는 아래와 같습니다.

• 탭에서 BApp 개발환경에 맞는 SDK를 다운로드 받아 설치합니다. 또는 REST API를 이용할 수도 있습니다.

• Prepare, Request 및 Result API를 이용하여 Klip 사용자 인증 또는 서명 기능을 BApp에 구현합니다. Prepare 스텝에서 App2App API 요청을 위한 key를 발급받고, Request 스텝에서 Klip을 실행합니다. 마지막 Result 스텝에서 요청에 대한 결과를 확인할 수 있습니다.

• 참고로 PC 또는 물리적으로 떨어진 모바일 환경에서는 QR code를 이용하여 Request 스텝을 처리할 수 있습니다. 자세한 내용은 탭을 참조하십시오.

이 문서에 관하여

Klip 개발자 가이드는 BApp 개발자 또는 파트너사가 Klip에서 제공하는 다양한 API를 활용하여 토큰(FT)을 조회하고 전송하거나 카드(NFT)를 발행, 조회, 전송 또는 삭제하도록 안내하는 문서입니다.

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

Klip REST API는 Klip Partners API와 App2App API로 구성됩니다.

Klip Partners API

Klip Partners API는 카드(NFT)를 발행, 전송, 삭제, 관리하는 기능 구현을 위한 REST API입니다. Klip Partners API는 카드 발행을 위한 Klip Partners 계정 로그인, 계정 관리 기능부터 카드를 발행, 전송, 관리하기 위한 API를 제공합니다.

App2App SDK는 여러분이 개발하는 애플리케이션에서 Klip을 더 쉽게 활용할 수 있도록 도와주는 SDK입니다.

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

Klip Partners API

Authentication

Klip Partners API를 사용하기 위해서는 JWT 기반 액세스 토큰 발급이 필요합니다. Klip Partners 회원 가입 시 등록한 로그인 ID와 비밀번호를 통해서 토큰을 발급 받을 수 있습니다. 발급된 토큰은 24시간 동안 유효하며 보통 만료 전에 재발급이 필요합니다. 발급된 토큰은 API 요청 헤더의 Authorization 필드에 토큰을 포함하는 방식으로 사용합니다.

Pagination

보유 카드 내역을 조회할 때 카드의 양의 많은 경우 한 번에 받으면 양이 많기 때문에 여러번 요청해야할 수 있습니다. 이를 위해서 조회 API에서는 결과값에 next_cursor를 함께 제공합니다. 일반적으로 카드 개수가 100개를 초과한다면 1번 호출 시 100개의 결과와 next_cursor 값을 받습니다. 나머지 카드를 조회하려면 next_cursor 값을 query 파라미터 cursor에 전달하여 API를 다시 호출해야합니다.

예들 들어 보유하고 있는 카드를 조회하면,

아래와 같은 형태의 응답을 받습니다.

남은 카드 목록을 조회하려면 next_cursor을 이용하여 아래와 같이 다시 호출합니다. next_cursor가 비어있을 때까지 계속 호출하여 보유한 전체 카드 목록을 얻을 수 있습니다.

Success Codes/Error Codes

요청이 성공하면 HTTP code 200을 받습니다. 만약 요청이 정상 처리되지 않으면 400, 401, 500의 HTTP code가 전달됩니다. 400은 요청이 잘못된 경우, 401은 유효하지 않은 액세스 토큰을 사용했을 때 리턴됩니다. 500은 서버에 알 수 없는 장애가 발생했을 때 리턴됩니다. 400 또는 401 에러는 구체적인 에러 코드와 메시지가 함께 전달됩니다.

에러 메시지는 JSON 포맷으로 전달되며 필드는 아래와 같습니다.

에러 메시지 종류는 아래와 같습니다.

Glossary

App2App API

Authentication

App2App API는 기본적으로 인증을 필요로 하지 않습니다. 하지만 BApp 별로 요청을 구분하기 위해서 request key를 발급하여 API 요청 시 사용합니다. 해당 key를 통해서 Klip 서버에서 요청 내용을 구분하여 컨텍스트를 유지하여 처리합니다. 일반적으로 request key를 발급받고 사용하는 절차는 아래와 같습니다.

• prepare API를 통해 인증 또는 서명할 내용을 전달하고 응답으로 request key를 전달 받습니다.

• 전달받은 request key를 이용하여 Deep Link(지정된 앱을 자동으로 실행하고 홈페이지가 아닌 특정 페이지로 가기 위한 URI)를 호출합니다. Klip 앱이 설치된 경우에는 Klip이 실행되고, 설치 되지 않은 경우에는 사용자가 앱을 다운로드받을 수 있습니다.

• 처리 결과는 result API를 통해서 polling하고 이 때 Query 파라미터 request_key에 어떤 요청에 대한 처리 결과를 얻고자 하는지를 전달합니다.

Pagination

보유 카드 내역을 조회할 때 카드의 양의 많은 경우 한 번에 받으면 양이 많기 때문에 여러번 요청해야할 수 있습니다. 이를 위해서 조회 API에서는 결과값에 next_cursor를 함께 제공합니다. 일반적으로 카드 개수가 100개를 초과한다면 1번 호출 시 100개의 결과와 next_cursor 값을 받습니다. 나머지 카드를 조회하려면 next_cursor 값을 query 파라미터 cursor에 전달하여 API를 다시 호출해야합니다.

예들 들어 보유하고 있는 카드를 조회하면,

아래와 같은 형태의 응답을 받습니다.

남은 카드 목록을 조회하려면 next_cursor을 이용하여 아래와 같이 다시 호출합니다. next_cursor가 비어있을 때까지 계속 호출하여 보유한 전체 카드 목록을 얻을 수 있습니다.

SDK

App2App API 기본적으로 REST API를 제공하지만, 각 BApp 개발환경에 맞게 사용할 수 있는 SDK를 제공합니다. 현재 지원하는 SDK 종류는 Android, iOS, 모바일 웹용 JavaScript입니다. 구체적인 내용은 를 참조하십시오.

Success Codes/Error Codes

요청이 성공하면 HTTP code 200을 받습니다. 만약 요청이 정상 처리되지 않으면 400, 500의 HTTP code가 전달됩니다. 400은 요청 데이터가 잘못됐거나 유효하지 않은 request_key를 사용했을 때 리턴됩니다. 500은 서버에 알 수 없는 장애가 발생했을 때 리턴됩니다. 400 에러는 구체적인 에러 코드와 메시지가 함께 전달됩니다. 자세한 내용은 각 API를 참조하십시오.

에러 메시지는 JSON 포맷으로 전달되며 필드는 아래와 같습니다.

이와 별개로 카드 조회 API (/v2/a2a/cards)는 request key와 관련이 없기 때문에 아래와 같은 형태로 에러가 전달됩니다.

에러 메시지 종류는 아래와 같습니다.

Glossary

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

본 문서는 Klip을 활용함에 있어 참고할 수 있는 각종 디자인/개발 가이드를 안내하고 있습니다.

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

월렛커넥트(WalletConnect)는 지갑과 DApp(탈중앙화 블록체인 애플리케이션)을 연동하기 위한 프로토콜입니다. 월렛커넥트를 이용하면 개별적으로 지갑과 DApp의 연동을 개발할 필요 없이, 하나의 프로토콜로 지갑의 연결과 서명이 가능해집니다.

클립 역시 현재 월렛커넥트 v1 및 v2를 통한 디앱 연동을 지원하고 있습니다. 다만 월렛커넥트를 통한 지갑 연동은 카카오톡 내 클립이 아닌 만 지원하는 점 참고 부탁드립니다.

월렛커넥트에 대한 보다 자세한 소개와 개발 문서는 아래를 참고 하시기 바랍니다.

• 월렛커넥트 홈페이지:

• 월렛커넥트 개발문서:

Klip API 튜토리얼은 Klip Partners REST API 튜토리얼과 App2App REST API 튜토리얼로 구성됩니다.

Klip Partners API

Klip Partners API는 카드(NFT)를 발행, 전송, 삭제, 관리하는 기능 구현을 위한 REST API입니다. Klip Partners API 튜토리얼은 Klip Partners 가입과 로그인, 카드 발행, 카드 정보 조회, 카드 전송, 카드와 계정 정보를 관리하는 방법을 상세하게 안내합니다.

App2App API

App2App API는 여러분의 "BApp"을 "Klip"과 연동하는 기능 구현을 위한 API입니다. App2App API 튜토리얼은 BApp이 Klip에 접근하기 위한 환경 설정부터 BApp에서 Klip에 요청을 보냄으로써 사용자 인증(auth), KAIA(=KLAY) 전송(send_klay), 토큰 전송(send_token), 카드 전송(send_card), 컨트랙트 실행(execute_contract) 작업을 수행하는 과정을 상세하게 안내합니다. App2App API 튜토리얼은 REST API를 기준으로 안내합니다.

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

JavaScript

브랜드 디자인 가이드

그라운드엑스 제품의 브랜드 정체성을 유지하기 위한 사용 가이드입니다.

1. 그라운드엑스

2. 클립

3. 클립 드롭스

4. 그리드

클립

1. 배너 디자인 가이드

클립에 표시되는 배너 제작 가이드입니다.

• 1-1. (카카오톡 내 클립) 홈 하단 리스트형 배너 가이드

  • 카카오톡 내 클립 홈 화면 하단에 노출되는 배너 제작 가이드입니다.

• 1-2. 홈 하단 랜덤형 배너 가이드

  • 클립 홈 화면 최하단에 노출되는 배너 제작 가이드입니다.

• 1-3. 홈 프로모션 팝업 배너 가이드

  • 클립 홈 화면 접근 시 팝업 형태로 노출되는 배너 제작 가이드입니다.

• 1-4. 홈 상단 클립 드롭스 작품 배너 가이드

  • 클립 홈 화면에 노출되는 클립 드롭스 배너 제작 가이드입니다.

2. 이미지 제작 가이드

클립에 서비스, 토큰, NFT 등록 시 필요한 이미지 제작 가이드입니다.

• 2-1. 서비스 정보 & 이미지 에셋 가이드

  • 클립 서비스 등록 시 필요한 앱 아이콘 및 스크린샷 가이드입니다.

• 2-2. 토큰 & NFT 가이드

3. 클립 로그인 버튼 가이드

app2app을 통해 클립을 연동하는 경우 참고할 수 있는 디자인 가이드입니다.

• 클립 로그인 버튼 가이드

  • 클립 로그인 기능을 구현할 때 필요한 버튼 가이드입니다.

클립 드롭스

1. 작품 제작 가이드

클립 드롭스 작품 및 크리에이터 이미지의 기술사양과 작품 정보를 참고할 수 있는 가이드입니다.

2. 배너 및 콘텐츠 디자인 가이드

클립 드롭스 내 홍보를 위한 배너 및 콘텐츠 제작 가이드입니다.

• 2-1. 통합 홈 배너 가이드

  • Klip Drops 홈페이지 상단에 노출되는 배너 제작 템플릿 파일입니다.

• 2-2. 작가 소개 콘텐츠 가이드

  • Klip Drops 홈페이지 상단 배너 클릭 시 새 탭으로 노출되는 작가 소개 콘텐츠 제작 가이드입니다.

3. 드롭스 파트너스 툴 가이드

드롭스 파트너스 툴 (DPT) 이용 방법과 신규 파트너의 필수 설정을 위한 가이드입니다.

이 문서 혹은 클립에 관한 문의는 을 방문해 도움을 받으십시오.

2025/09/15

• 클립의 XRPL (리플) 네트워크 지원에 따라 지갑 연동의 주소 응답값에 XRPL 주소 포함

2025/08/18

• 클립 지원 네트워크 확장에 따른 지갑 연동의 주소 응답값 변경

• 서명 요청에 eth_signTypedData_v4 지원

2025/02/11

• iOS SPM을 사용하여 SDK를 적용하는 방법 추가

• OS별 request 함수 호출 이슈 수정을 위한 JavaScript SDK 2.3.3 배포

2024/11/18

• 클립 호출 방식 변경에 따른 App2App REST API Request 내용 수정

• 클립 호출 방식 변경에 따른 JavaScript/Android/iOS SDK 새 버전 배포 및 내용 수정

2024/10/31

• Klaytn -> Kaia 변경에 따른 내용 수정 (문서만 변경된 것으로, 기능 스펙은 호환성이 보장됨)

• Kaia의 새로운 서명 표준에 따라, App2App 요청 타입에 sign_message_eip191 추가

2024/08/01

• Klip Partners 서비스 종료에 따른 내용 수정

2024/03/18

• 에 max_value를 사용하는 attributes에 대한 설명 및 예시 추가

2023/09/05

• 를 확인하고 다운로드할 수 있는 페이지 추가

• 기존의 문서 위치를 Tutorial에서 밑으로 이동

2023/08/03

• 월렛커넥트 (WalletConnect) 지원

2023/06/05

• Klip 로그인 버튼 가이드에 Klip 2.0 로고 반영

2023/05/30

• App2App Polygon 체인 지원

2023/04/11

• Card Minting API 섹션 이름을 좀 더 직관적이게 Klip Partners API로 변경

2023/04/05

• App2App JavaScript SDK 2.2.1 배포

• App2App Deeplink 요청 scheme을 인톡클립 우선 호출하도록 변경

2023/03/10

• App2App Prepare 요청 시 가스추정량을 계산할 수 있는 경우 함께 반환

2023/01/27

• App2App Ethereum 체인 지원

• App2App 트랜잭션 수수료 대납 가이드 추가

• Contract execute 업데이트

  • param type 오류에 대한 상세 정보 반환

2022/12/19

• Klip 자산 지원 정책 변경과 관련된 주의 사항 / 안내 추가

2022/11/15

• Klip에서 지원하는 메타데이터 속성 표준 안내 페이지 추가

2022/11/02

• Contract execute 업데이트

  • tuple 지원

  • encoded_function_call 지원

• Sign message 업데이트

2022/09/15

• Klip 앱 지원을 위한 SDK 업데이트 (v2.2.0)

• App2App sign message 예제 코드 추가

2022/08/18

• Klip 앱 지원을 위한 SDK 업데이트 (v2.1.0)

2022/08/17

• App2App sign message 기능 설명 추가

2022/03/08

• 개발자 포럼 URL 변경

2021/09/30

• App2App API의 Response status에 canceled 추가

2021/07/28

• animation_url 필드 제약 사항 업데이트

2021/07/13

• App2App 인증 API 사용 시 주의사항 문구 추가

2021/07/07

• App2App SDK 오픈소스 고지문에서 사명 변경

  변경 전

  변경 후

2021/06/28

• App2App 인증 요청 버튼 문구 관련 가이드 추가

2021/05/10

• 신규 API 추가

  • 임의의 NFT resource 파일을 업로드할 수 있는 API를 추가했습니다.

• Card Minting API Request에 필드 추가

  • animation_url

2021/03/08

• 사명 변경 및 이메일 주소 업데이트

  변경 전

  변경 후

2021/02/03

• 특정 Klip 회원에게 발행 및 전송하기 API 응답 필드에 트랜잭션 해시가 추가됐습니다.

• Card Minting API의 Request에 필드 추가

  • secure 필드에 카드 소유자만 볼 수 있는 속성을 설정할 수 있습니다.

  • status_url

2021/01/12

• 신규 API 추가

  • 트랜잭션 해시로 처리 결과를 확인할 수 있는 API가 추가됐습니다.

  • 이번 달 현재까지 발행한 카드 개수를 조회할 수 있는 API가 추가됐습니다.

• Introduction 내 링크 오류 수정

2020/11/30

• QR Code 기반 App2App 처리 기능 신규 추가

  • PC 또는 물리적으로 떨어진 환경에서 App2App 기능을 실행할 수 있습니다.

  • 모바일 카메라 앱 또는 Klip에서 QR Code를 인식하면 App2App 요청을 처리하는 방식으로 동작합니다.

• 에스크로 카드 전송 API 신규 추가

2020/10/26

• App2App API 추가

  • 외부 서비스에서 Klip 사용자 주소를 가져오는 기능을 제공합니다.

  • 외부 서비스에서 Klip을 이용해 KLAY 및 대체 가능한 토큰(FT), 카드(NFT)를 전송하거나 스마트 컨트랙트를 실행하는 기능을 제공합니다.

2020/08/26

• Mint Card To User, Mint Card To Klip Member API로 카드 발행 시 카드 메타데이터에 입력하는 Optional 필드 추가

  • group_name

  • group_icon

2020/07/31

• Mint Card API를 Mint Card To User API로 이름 변경

  • EOA를 가진 사용자(Klip 회원 또는 비회원)에게 카드를 발행합니다.

  • 발행 시 사용자 EOA를 사용합니다.

• Mint Card To Klip Member API 신규 추가

2020/07/16

• Get Card Information By BApp API Response에서 order_no 변수명을 nft_order_no로 변경

2020/06/16

• Send Card API의 Request Body Parameter에서 to_klip_id 사용 중지

2020/05/28

• 가 Klip에 로그인하고 카드(NFT)를 발행/전송/조회할 수 있도록 Klip API 개발

메타데이터 속성

Klip에서 지원하는 속성값의 이름과 설명은 다음과 같습니다. OpenSea에서 사용하는 속성값과 일부 명칭 차이가 있으니 유의 바랍니다.

권장 이미지 및 영상 규격

Klip에 노출되는 NFT 이미지와 영상은 각각 권장 규격과 파일 형식이 존재합니다. 아래 기준을 따르지 않는 경우 NFT 이미지 또는 영상이 정상적으로 표시/재생되지 않을 수 있습니다.

• 이미지 규격

  • 최소 크기: 1024px x 1024px 이상

  • 최대 크기: 23170px x 23170px 이하

  • 용량: 5MB 이하

구조와 예시

Klip에서 지원하는 속성에 맞춰 작성된 메타데이터의 예시는 아래와 같습니다.

여기에서 status_url에 지정된 URL 주소를 통한 응답값 예시는 아래와 같습니다.

위의 예시 메타데이터로 발행한 NFT가 Klip에서 어떻게 보이는지 살펴보겠습니다.

먼저 메타데이터에 포함된 image 파일이 NFT 대표 이미지로 나타나고, 그 아래로 name과 description이 표시됩니다. animation_url을 추가하여 동영상이 있는 경우에도 image는 필수 값으로, 여기에 지정된 이미지가 대표 이미지로 표시되고 동영상은 대표 이미지를 클릭해 확인할 수 있습니다. name 아래에 group_icon과 group_name 정보가 표시됩니다. 그룹이 지정되면 콜렉션 내의 NFT 목록에서 상단에 필터 메뉴가 표시되어 빠른 분류 및 검색이 가능합니다. description 아래에 hashtags를 통해 지정한 해시태그 값들이 #가 자동으로 붙어 표시됩니다.

status_url로 동적 정보가 지정된 경우, 그 하단에 상태값과 속성을 실시간으로 가져와 NFT 정보에 보여줍니다.

그 하단으로 attributes를 통해 지정한 세부 속성값이 trait_type - value 쌍으로(max_value가 함께 지정된 경우 최대값이 함께 표시), external_link를 통해 지정한 URL이 클릭 가능한 관련 링크로, custom_links를 통해 지정한 레이블명(display_name)과 URL(value)값이 각각 버튼 링크로 표시됩니다. 외부 링크는 클릭 시, 외부 브라우저를 통해 앱 전환되어 열리게 됩니다. 아울러 본 NFT는 sendable이 true로 지정되어있기 때문에 "보내기" 버튼이 화면 오른쪽 상단의 메뉴 아이콘 버튼을 통해 제공됩니다. 그 이하로 표시되는 내용들은 NFT의 수신 내역과 콜렉션에 대한 정보들로, 메타데이터와 직접적으로 관련 있는 내용은 아닙니다.

이렇게 외부에서 Klip의 표준에 맞춰 구성된 메타데이터가 Klip UI 상 어떻게 표시되는지 알아보았습니다. 본 스크린샷은 환경에 따라, 또는 추후 Klip UI 개선/변경에 따라 다소 차이가 발생할 수 있습니다.

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

요구 사항

• iOS 12.0 이상

• Swift 5.0 이상

• Xcode 13.4 이상

환경 설정

Klip iOS SDK는 별도의 가입 절차가 필요하지 않습니다. HTTP 통신이 가능한 어느 환경에서도 동작합니다. 다만, 기본적으로 Klip 앱이 설치된 환경에서 호출해야 합니다. Klip 앱을 실행하여 Klip 사용자의 승인을 받아야 하기 때문입니다.

1. Klip SDK 적용

Option 1. SPM 사용

2.3.0 이상 버전만 사용 가능합니다.

option 2. SDK 다운로드하여 적용

1. Klip SDK 다운로드

페이지에서 Klip iOS SDK를 다운받습니다.

2. Klip SDK Framework 추가

Klip SDK Framework를 Import하여 개발 프로젝트에 추가

1. 개발 중인 프로젝트를 Xcode로 실행

2. Xcode > 개발 프로젝트의 TARGETS 선택 > General Tab > Framworks, Libraries, and Embedded Content Tab > 왼쪽 하단의 + 버튼을 클릭

3. Source Directory에 다운받은 Klip SDK 프로젝트의 sdk 디렉토리를 선택, 클릭한 후 Next를 클릭

4. 왼쪽의 Project navigator의 Frameworks에 해당 SDK가 Import 되었는지 확인 후 build 수행

Klip SDK 소스가 개발 프로젝트에 복사되고 라이브러리 코드를 직접 수정할 수 있습니다.

2. Info.plist 설정

앱 실행 허용 목록(Allowlist) 등록하기

iOS 9.0 이상에서 iOS SDK로 Klip 등 애플리케이션 실행 기능을 이용하려면 Info.plist 파일에 설정을 추가하여 커스텀 스킴 정보를 등록해야 합니다.

[Info] > [Custom iOS Target Properties]에 Array 타입 키(Key)인 LSApplicationQueriesSchemes를 추가하고, 해당 키의 'Item'으로 커스텀 스킴에 사용할 값인 'klip'을 추가합니다.

4. Source Import 설정

v2.1.0 이상

v2.1.0 미만

API

개요

App2App API 요청은 크게 prepare, request, getResult의 순서로 진행이 됩니다.

• prepare는 어떠한 요청을 할지 요청을 정의하는 단계로 총 5가지 종류의 요청이 존재

• request는 함수 호출을 통해 Klip으로 화면이 전환되어 실제 서명 프로세스를 진행

• getResult는 함수 호출을 통해 결과값을 받고 확인

추가적으로 getCardList는 BApp 개발의 편의를 위해 Klip 사용자의 NFT 목록을 받아올 수 있도록 제공되는 함수입니다.

KlipSDK.shared

Klip SDK를 사용하기 위한 인스턴스를 생성합니다.

Return Value

Example

KlipSDK.shared.prepare

KlipSDK.shared.prepare(request: KlipRequest, bappInfo: BAppInfo, completion: @escaping(KlipCallback<KlipTxResponse>) -> Void) App2App API 요청 처리를 준비하고 request key를 발급합니다.

Request 값에 사용할 객체

• Klip 연결 타입(=인증)의 경우 AuthRequest

• KAIA(=KLAY) 전송 타입의 경우 KlayTxRequest

• Token 전송 타입의 경우 TokenTxRequest

Parameters

Klip 사용자에게 동의 요청시, request와 bappInfo에 입력된 정보가 출력됩니다. 응답 결과에 포함된 request key는 사용자에게 트랜잭션을 요청하기 위한 컨텍스트 키의 역할을 수행하며, 사용자 동의 요청 및 결과확인 API와 함께 사용 됩니다.

Example 1. 사용자 정보 획득하기

Example 2. KAIA(=KLAY) 전송하기

Example 3. Token 전송하기

Example 4. Card 전송하기

Example 5. Contract 실행하기

Example 6. Sign Message 요청하기

KlipSDK.shared.request

KlipSDK.shared.request(requestKey: String) -> Void Deep Link를 이용하여 Klip에 인증 또는 서명을 요청합니다. 실행 중인 스마트폰 기기에 Klip 앱이 설치되지 않았거나 자동 실행할 수 없는 경우 'Klip 소개 페이지(https://klipwallet.com)' 로 이동하여 사용자는 Klip 앱을 다운로드받을 수 있습니다. requestKey에는 prepare 단계에서 Klip 서버로부터 받은 요청 번호를 사용합니다.

PC 환경에서 QR code를 이용한 request 스텝 처리는 항목을 참조하십시오.

Parameters

Example

KlipSDK.shared.getResult

KlipSDK.shared.getResult(requestKey: String, completion: @escaping(KlipCallback<KlipTxResponse>) -> Void) App2App API 요청에 대한 결과를 확인합니다. requestKey에는 prepare 및 request 단계에서 사용한 요청 번호를 사용합니다.

Parameters

Example

KlipSDK.shared.getCardList

KlipSDK.shared.getCardList(cardAddress: String, userAddress: String, cursor: String?, completion: @escaping(KlipCallback<CardListResponse>) -> Void) 사용자의 모든 카드 중 특정 카드의 목록을 가져옵니다.

Parameters

Example

Error Code

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

App2App REST API Tutorial

요구 사항

요구 사항

• (npm 이용하여 설치하는 경우) node 10 이상 권장

환경 설정

Klip JavaScript SDK는 별도의 가입 절차가 필요하지 않습니다. HTTP 통신이 가능한 어느 환경에서도 동작합니다. 다만, 기본적으로 Klip 앱이 설치된 환경에서 호출해야 합니다. Klip 앱을 실행하여 Klip 사용자의 승인을 받아야 하기 때문입니다.

npm을 이용하는 경우

npm install klip-sdk 혹은 yarn add klip-sdk 커맨드를 통해 설치 후 다음과 같이 ES module import 방식으로 사용합니다.

직접 파일을 다운 받아 사용하는 경우

탭에서 Klip JavaScript SDK를 다운받습니다. 다운 받은 파일을 레포지토리에 위치시킨 후 HTML파일에 다음과 같이 스트립트 태그를 삽입합니다.

이후 글로벌 네임스페이스에 선언된 klipSDK 변수를 활용하여 각 메소드에 접근합니다.

API

개요

App2App API 요청은 크게 prepare, request, getResult의 순서로 진행이 됩니다.

• prepare는 어떠한 요청을 할지 요청을 정의하는 단계로 총 5가지 종류의 요청이 존재

• request는 함수 호출을 통해 Klip으로 화면이 전환되어 실제 서명 프로세스를 진행

• getResult는 함수 호출을 통해 결과값을 받고 확인

추가적으로 getCardList는 BApp 개발의 편의를 위해 Klip 사용자의 NFT 목록을 받아올 수 있도록 제공되는 함수입니다.

prepare

App2App API 요청을 준비하고 request key를 받습니다.

사용 가능한 요청 유형

• Klip 연결 타입(=인증)의 경우 auth

• KAIA(=KLAY) 전송 타입의 경우 sendKLAY

• Token 전송 타입의 경우 sendToken

prepare.auth

사용자의 정보를 획득하는 요청입니다.

Parameters

Example

prepare.sendKLAY

사용자의 KAIA(=KLAY)를 특정 주소로 전송하는 요청입니다.

Parameters

Example

prepare.sendToken

사용자가 보유한 토큰을 특정 주소로 전송하는 요청입니다.

Parameters

Example

prepare.sendCard

사용자가 보유한 카드(NFT)를 특정 주소로 전송하는 요청입니다.

Parameters

Example

prepare.executeContract

사용자가 특정 컨트랙트의 함수를 실행하도록 하는 요청입니다.

Parameters

Example

prepare.signMessage

사용자가 Klip 계정으로 메시지를 서명하는 요청입니다. 기존 Klaytn 표준에 따라 "\x19Klaytn Signed Message:\n" + len(message)의 접두사를 붙여 서명합니다.

Parameters

Example

request

Deep Link를 이용하여 Klip에 인증 또는 서명을 요청합니다. 실행 중인 스마트폰 기기에 Klip 앱이 설치되지 않았거나 자동 실행할 수 없는 경우 'Klip 소개 페이지(https://klipwallet.com)' 로 이동하여 사용자는 Klip 앱을 다운로드받을 수 있습니다. requestKey에는 prepare 단계에서 Klip 서버로부터 받은 요청 번호를 사용합니다.

PC 환경에서 QR code를 이용한 request 스텝 처리는 항목을 참조하십시오.

Parameters

Example

getResult

App2App API 요청에 대한 결과를 확인합니다. requestKey에는 prepare 및 request 단계에서 사용한 요청 번호를 사용합니다.

Parameters

Example

getCardList

사용자의 카드 (NFT) 보유 목록을 가져옵니다. 조회하고자 하는 NFT 컨트랙트 주소를 알고 있어야 하며, Klip에서 지원하는 컨트랙트만 가능합니다.

Parameters

Example

Error Code

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

※ 개요

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

Prepare

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

• 인증

• 토큰 전송

• 카드 전송

• 스마트 컨트랙트 실행

인증

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

Klip 로그인 버튼 가이드

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

• Klip App2App 버튼 템플릿

토큰 전송

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

카드 전송

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

스마트 컨트랙트 실행

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

메시지 서명

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

Request

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

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

예를 들어, 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

Request Body

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 발급 방법은 를 참고하시기 바라며, 문의사항은 를 이용하여 주시기 바랍니다.

transaction object 예시

1. type: send_token

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

2. type: send_card

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

3. type: 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

message object 예시

1. type: 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와 동일하게 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 배열이여야 합니다.

3. type: sign_typedData_v4

여기에서 vaule 값은 EIP-712에서 정의된 json 형태의 구조화된 메시지로써, 정확한 스펙은 를 참고하시기 바랍니다.

Request Example

Response Details

자세한 내용은 을 확인하십시오.

Request

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

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

Query Parameters

Request Example

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

iOS 또는 Android 환경

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

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

Result

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

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

Query Parameters