Kaia는 기존의 Klaytn과 Finschia 블록체인 네트워크가 통합되어 운영되는 블록체인의 새 이름입니다. 이에 따라 본 문서는 대부분 Klaytn을 Kaia로 / KLAY를 KAIA로 지칭하지만, 하위 호환성을 위해 기존 호출과 응답에서 사용되던 klaytn, KLAY 등의 키워드는 동일하게 유지되는 점 참고 부탁드립니다.
Klip Partners API Tutorial
1. Klip Partners
1-1. 가입 신청과 승인
카드를 발행하려면 먼저 Klip Partners 사이트에 가입해야 합니다. 가입을 신청하면 Klip 운영진과 별도로 협의한 후 가입이 승인됩니다. 가입이 승인되면 가입 승인 확인 메일을 받으며 Klip Partners에 로그인할 수 있습니다. 서비스 이용을 희망하는 파트너사는 원활한 사업 논의를 위해서 (1)회사 소개, (2)카드 활용 목적, (3)카드 활용 방안 등을 서면으로 정리해 klip-partners@groundx.xyz로 보내주시길 바랍니다.
Klip Partners 웹사이트는 허가된 사용자만 접근 가능하나, Klip Partners 서비스가 2024년 7월 31일자로 종료되어 현재는 신규 가입 신청을 받지 않고 있습니다. 아울러 기존 사용자 역시 2024년 8월 1일부터 Klip Partners API를 호출할 수 없습니다.
1-2. 로그인
으로 로그인 ID와 비밀번호( email과 password)를 Klip Partners에 보내고 로그인을 요청합니다.
카드 정보가 정상 조회되었다면 계정이 쓰는 모든 BApp 목록과 BApp별 카드 정보를 받습니다.
bapps에서 bapp은 Klip 파트너사가 서비스하는 BApp입니다.
cards에서 card는 이 BApp에서 쓰이는 Klip 카드입니다. BApp에는 카드 1종류가 들어있습니다.
nft_id란 이 card를 블록체인 상에 만드는 스마트 컨트랙트의 ID입니다.
nft와 bapp은 항상 1:1로 맵핑됩니다.
card_uri는 카드 메타데이터가 담긴 JSON 파일이 있는 URL입니다.
카드 메타데이터는 name, description, image, background_color, attributes 등 카드를 발행할 때 정의한 카드 기본 정보입니다.
1회 요청에 BApp 정보를 최대 100개까지 받습니다. 불러올 BApp 개수가 100개 이상이면 다음 BApp 정보를 불러올 수 있는 페이지네이션 커서값인 bapps.next_cursor로 나머지 카드 정보를 받습니다.
나머지 BApp 정보를 받으려면 Query 파라미터 cursor에 이전 호출에서 받은 bapps.next_cursor를 넣고 API를 다시 호출합니다.
위 API 응답값을 보면 발행자는 BApp 2개를 사용하며, 첫 번째 BApp에는 카드에 3개가, 두 번째 BApp에는 카드 1개가 있습니다.
bapps[0].cards 배열을 보면 카드 생성/업데이트 시간, 카드 소유자 주소, 카드를 보내준 사람 주소, 카드 발행 트랜잭션 해시 등 각 카드에 관한 상세 정보를 확인할 수 있습니다.
한 번에 조회할 BApp 개수가 100개를 초과한다면 1회 호출 시 BApp 100개 정보만 받고 bapps.next_cursor값을 받습니다.
나머지 BApp 정보를 조회하려면 bapps.next_cursor값을 Query 파라미터 cursor에 전달하고 API를 다시 호출해야 합니다.
요청이 정상 처리되지 않으면 아래 값을 받습니다.
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
BApp별로 보유한 카드 목록을 조회하지 못했습니다.
3-2. 카드 정보만 조회하기
//Get Card Information - '52' is the `nft_id` of our interest.
curl "https://api.klipwallet.com/v2/wallet/nft/52" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"
카드 정보가 정상 조회되었다면 계정이 이 BApp에서 소유한 카드 목록과 정보를 받습니다.
cards에서 card는 이 bapp에서 쓰이는 Klip 카드입니다. bapp에는 카드 1종류가 들어있습니다.
Query 파라미터로 cursor 또는 isAll 둘 중 하나만 사용해야 합니다(isAll이 false이면 cursor를 사용할 수 있습니다).
cursor를 사용하면 Pagination을 사용합니다.
1회 요청에 최대 카드 100개의 정보를 받습니다.
정보를 불러울 카드가 100개를 초과 시 다음 카드 정보를 불러올 수 있는 커서값인 next_cursor로 나머지 카드 정보를 받습니다.
나머지 카드 정보를 받으려면 cursor에 이전 호출에서 받은 next_cursor를 넣고 API를 다시 호출합니다.
위 예시에서 cards.next_cursor값이 존재하므로 이 계정은 conan 카드를 100개 이상 가지고 있습니다.
한 번에 조회할 카드 개수가 100개를 초과한다면 1회 호출 시 카드 100개 정보만 받고 cards.next_cursor값을 받습니다.
나머지 카드 정보를 조회하려면 cards.next_cursor값을 Query 파라미터 cursor에 전달하고 API를 다시 호출해야 합니다.
예를 들어, 정보를 불러올 카드 개수가 150개라면, 먼저 API를 호출하여 카드 100개의 정보와 cards.next_cursor값을 받습니다.
그리고 동일한 API를 다시 호출할 때 cards.next_cursor값을 Query 파라미터 cursor로 사용하면 나머지 50개의 정보를 받습니다.
요청이 정상 처리되지 않으면 아래 값을 받습니다.
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
카드 정보를 조회하지 못했습니다.
//Get Card Information, cards.next_cursor 값을 cursor로 사용
curl "https://api.klipwallet.com/v2/wallet/nft/52?cursor=mrzedXOE9OeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
BApp별로 보유한 카드 목록을 조회하지 못했습니다.
//BApp 1 나머지 카드 정보 수신 예시
//Get Card Information, bapps[0].cards_next_cursor값을 cursor로 사용
curl "https://api.klipwallet.com/v2/wallet/nft/60?cursor=gKvkL1lPYv1P93dpEWgaBzrq7XZ4LwjpgNe39AH9Dt3C1iWkubJtGotkrsQs4qSwdIJMHr3HKrhlCqJupwToWCd0T55IKhLzARM60N5xAGJQbKomeDkVl2O8WxMB0GQ9" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
카드 정보를 조회하지 못했습니다.
//BApp 2 나머지 카드 정보 수신 예시
//Get Card Information, bapps[1].cards_next_cursor값을 cursor로 사용
curl "https://api.klipwallet.com/v2/wallet/nft/61?cursor=Xrzed2Ot9LeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
카드 정보를 조회하지 못했습니다.
3-4. 카드 개수에 관계없이 한 번에 조회하기
//Get All Card Information - '52' is the `nft_id` of our interest.
curl "https://api.klipwallet.com/v2/wallet/nft/52?isAll=true" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"
카드 정보가 정상 조회되었다면 계정이 이 BApp에서 쓰는 모든 카드 목록과 정보를 받습니다.
Query 파라미터로 cursor 또는 isAll 둘 중 하나만 사용해야 합니다(isAll이 false이면 cursor를 사용할 수 있습니다).
요청이 정상 처리되지 않으면 아래 값을 받습니다.
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
카드 정보를 조회하지 못했습니다.
3-5. Secure 리소스 포함 이미지 또는 동영상 정보 조회하기
파트너사에서 업로드한 secure 미디어 파일 목록을 조회할 수 있습니다. 반환되는 파일 목록 형태는 <uploaded_secure_url>/<uploaded_files[0]>?<uploaded_secure_query>이며, 사용하려면 Klip 팀으로 먼저 문의하시기 바랍니다.
//게임 아이템 카드인 마법 검 카드를 보내기 위한 send_info.json 파일 내용 예시
{
"pin": "91B4D142823F7D20C5F08DF69122DE43F35F057A988D9619F6D3138485C9A203",
"to_address": "0xb1764B96da889Cc2F043025aa368517C80e86795",
"card_name": "Magic Sword"
}
//게임 아이템 카드인 마법 검 카드를 보내기 위한 send_info.json 파일 내용 예시
{
"pin": "91B4D142823F7D20C5F08DF69122DE43F35F057A988D9619F6D3138485C9A203",
"to_person": ["홍길동", "010-1111-2222"]
"card_name": "Magic Sword"
}
이 파일에는 카드 이름, pin, 카드를 받는 사람이 Klip 회원에 가입 시 사용한 실명과 전화번호가 담겨 있습니다.
pin은 트랜잭션 서명에 개인 키 대신 사용됩니다.
to_person 파라미터에 전달한 실명과 전화번호로 가입한 Klip 회원이 없다면 전송에 실패합니다.
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
카드 전송에 실패했습니다.
5-3. 에스크로 전송 링크 생성
에스크로 전송은 Klip 회원에게 카드를 바로 전송하지 않고 카드 지급 링크를 통해서 전송하는 기능입니다. 에스크로 전송 기능을 활용하기 위해서는 먼저 카드 지급 링크 생성 API를 호출해야합니다. 기본적으로 보유한 카드에 한하여 에스크로 생성을 요청할 수 있습니다. 에스크로 생성 후 해당 카드는 더 이상 카드 보유 목록에서 조회되지 않습니다.
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
카드 전송에 실패했습니다.
6. 트랜잭션
6-1. 처리 결과 조회
트랜잭션 처리 결과가 블록에 최종 성공으로 기록됐는지 여부를 조회할 수 있습니다. 트랜잭션 요청 후 곧바로 결과를 조회하는 경우 4700: no transaction receipt 에러가 발생할 수 있습니다. 대략 2초 이상의 딜레이를 두고 에러가 뜨지 않을 때까지 수회 반복 호출하는 것을 권장합니다.
에러가 발생하지 않았다면 카드가 정상 삭제된 것입니다. 카드가 정상 삭제되었다면 카드 삭제 트랜잭션 해시값을 받습니다.
발행한 카드만 삭제할 수 있으며, 다른 사람에게 보낸 카드는 삭제할 수 없습니다.
카드를 삭제해도 카드 이미지는 삭제되지 않습니다.
요청이 정상 처리되지 않으면 아래 값을 받습니다.
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
카드 삭제에 실패하였습니다. 삭제와 관련해 정확한 정보를 확인하려면 보유 카드를 조회하십시오.
Klip Partners에 가입하면 블록체인상에 여러분의 주소와 카드를 발행할 스마트 컨트랙트가 생성됩니다. klaytn_address는 블록체인에 생성된 여러분의 주소이며 contract_address는 카드를 발행할 스마트 컨트랙트 주소()입니다.
카드 이미지는 카드가 Klip 사용자에게 보일 모양입니다. 카드를 발행하려면 이 카드 이미지를 먼저 업로드해야 합니다. 로 카드 이미지 파일, 로그인 시 받은 access_token을 Klip Partners에 보내고 이미지 업로드를 요청합니다.
로 카드를 발행하려면 Upload Image API로 먼저 카드 이미지를 업로드해야 합니다.
로 mint_info.json 파일, 로그인 시 받은 access_token을 Klip Partners에 보내고 카드 발행을 요청합니다. 업로드한 카드 이미지를 사용합니다. EOA를 가진 사용자라면 누구나 카드를 발행받을 수 있습니다.
pin은 핀 번호(Klip Partners 회원 가입 시 설정한 6자리 숫자)를 해시()한 64자리 Hex String 값입니다.
to_address는 카드를 발행받을 사용자 주소들이 담긴 배열입니다.
to_address에 넣을 수 있는 주소 개수는 API 호출 1회당 최대 200개입니다.
카드가 정상 발행되었다면 카드를 발행한 스마트 컨트랙트 트랜잭션 해시값을 위와 같이 받습니다. 전달받은 트랜잭션 해시값을 에서 조회할 수 있습니다. 이 해시값을 조회하면 카드 발행 트랜잭션이 정상 실행되었는지 확인할 수 있습니다.
로 mint_info.json 파일, 로그인 시 받은 access_token을 Klip Partners에 보내고 카드 발행을 요청합니다. Klip 회원의 실명과 전화번호를 사용하여 Klip 회원에게만 카드를 발행합니다.
pin은 핀 번호(Klip Partners 회원 가입 시 설정한 6자리 숫자)를 해시()한 64자리 Hex String 값입니다.
카드를 발행할 때 animation_url 필드를 설정하기 위해서는 카드 동영상을 먼저 업로드해야 합니다. 로 카드 동영상 파일, 로그인 시 받은 access_token을 Klip Partners에 보내고 동영상 업로드를 요청합니다.
카드를 발행했다면 발행한 카드를 포함해 소유한 카드 정보를 BApp 정보와 함께 조회할 수 있습니다. 으로 로그인 시 받은 access_token을 보내고 BApp별 카드 정보 조회를 요청합니다.
본 API의 경우, 클립의 자산 리스팅 정책 변경에 따라 일부 새로운 카드는 조회가 불가능할 수도 있습니다. 대신 API 사용을 권장합니다.
또 1회 요청에 BApp별로 BApp에서 쓰이는 카드 정보를 최대 100개까지 받습니다. BApp별로 카드가 100개를 초과할 경우 나머지 카드 정보를 받으려면, API로 각 카드 정보를 확인해야 합니다.
각 BApp은 카드를 생성하는 스마트 컨트랙트 ID인 nft_id가 있습니다. 으로 Path 파라미터 nft_id, 로그인 시 받은 access_token을 Klip Partners에 보내고 BApp별로 카드 정보를 조회합니다.
nft_id는 API로 받은 BApp 정보에서 확인합니다.
으로 cards.next_cursor값과 로그인 시 받은 access_token을 Klip Partners에 보내고 나머지 카드 정보 조회를 요청합니다.
cards 배열의 상세 정보는 으로 받는bapps[i].cards배열 정보와 동일합니다.
은 1회 요청에 각 BApp당 카드 정보를 최대 100개까지만 반환합니다. BApp별 카드가 100개를 초과할 때 나머지 카드 정보까지 받으려면, 을 따로 호출해야 합니다. 101번째 카드부터 조회하려면 bapps[i].cards_next_cursor를 Query 파라미터 cursor로 사용해 을 호출합니다.
예를 들어, BApp을 2개 가지고 있고 BApp1에 카드 150개, BApp2에 카드 200개가 있을 때 을 호출하면 BApp1 카드 100개, BApp2 카드 100개의 정보만을 받습니다. 으로 로그인 시 받은 access_token을 보내고 BApp별 카드 정보 조회를 요청해야 합니다.
본 API의 경우, 클립의 자산 리스팅 정책 변경에 따라 일부 새로운 카드는 조회가 불가능할 수도 있습니다. 대신 API 사용을 권장합니다.
BApp1 나머지 50개 카드 정보를 받으려면 Query 파라미터 cursor에 bapps[0].cards_next_cursor값인 gKvkL1lPYv1P93dpE...를 전달해 을 호출해야 합니다.
으로 gKvkL1lPYv1P93dpE...과 로그인 시 받은 access_token을 Klip Partners에 보내고 BApp1 나머지 카드 50개 정보 수신을 요청합니다.
BApp2 나머지 카드 100개 정보를 받으려면 Query 파라미터 cursor에 bapps[1].cards_next_cursor값인 Xrzed2Ot9LeEor...을 전달해 을 호출해야 합니다. 으로 Xrzed2Ot9LeEor...과 로그인 시 받은 access_token을 Klip Partners에 보내고 BApp2 나머지 카드 100개 정보 수신을 요청합니다.
페이지네이션으로 카드 정보를 100개씩 확인하지 않고 한 번에 모든 카드 정보를 받으려면 으로 Query 파라미터 isAll, Path 파라미터 nft_id, 로그인 시 받은 access_token을 Klip Partners에 보내고 모든 카드 정보를 요청합니다.
cards 배열의 상세 정보는 으로 받는bapps[i].cards배열 정보와 동일합니다.
로 Klip Partners에 로그인 시 받은 access_token, send_info.json 파일, 전송할 BApp 카드의 nft_id와 card_id(Path 파라미터)를 보내고 현재 계정 주소에 있는 카드를 다른 사람의 주소로 전송하도록 요청합니다.
이 파일에는 카드 이름, pin, 카드를 받는 사람의 주소가 담겨 있습니다.
pin은 핀 번호(Klip Partners 회원 가입 시 설정한 6자리 숫자)를 해시()한 64자리 Hex String 값입니다.
전송에 성공하면 카드 수신자 주소, 전송 실패 횟수, 카드를 전송한 트랜잭션 해시값을 받습니다. 전송에 성공하면 fail_count 0을 받습니다.
로 Klip Partners에 로그인 시 받은 access_token, send_info.json 파일, 전송할 BApp 카드의 nft_id와 card_id(Path 파라미터)를 보내고 현재 계정 주소에 있는 카드를 다른 사람에게 전송하도록 요청합니다.
pin은 핀 번호(Klip Partners 회원 가입 시 설정한 6자리 숫자)를 해시()한 64자리 Hex String 값입니다.
이 파일에는 pin, contract_address는 카드를 발행한 스마트 컨트랙트 주소()가 들어갑니다.
pin은 핀 번호(Klip Partners 회원 가입 시 설정한 6자리 숫자)를 해시()한 64자리 Hex String 값입니다.
이 파일에는 pin, contract_address는 카드를 발행한 스마트 컨트랙트 주소(), 에스크로 전송할 card_id의 배열인 card_ids가 들어갑니다.
pin은 핀 번호(Klip Partners 회원 가입 시 설정한 6자리 숫자)를 해시()한 64자리 Hex String 값입니다.
cards 배열의 상세 정보는 의 Response Detail 항목을 참조하십시오.
이 파일에는 pin, contract_address는 카드를 발행한 스마트 컨트랙트 주소(), 취소할 card_id의 배열인 card_ids가 들어갑니다.
pin은 핀 번호(Klip Partners 회원 가입 시 설정한 6자리 숫자)를 해시()한 64자리 Hex String 값입니다.
로 Klip Partners에 old_password, new_password, 로그인 시 받은 access_token을 보내고 이전 비밀번호에서 새로운 비밀번호로 교체를 요청합니다.
old_password, new_password는 기존 비밀번호/새롭게 사용할 비밀번호를 해시()한 64자리 Hex String 값입니다.
으로 Klip Partners에 이전 핀 번호, 새로운 핀 번호, 로그인 시 받은 access_token을 보내고 새로운 핀 번호로 핀 번호 교체를 요청합니다.
old_pin과 new_pin은 기존 핀 번호/새롭게 사용할 핀 번호를 해시()한 64자리 Hex String 값입니다.
로 Klip Partners에 delete_info.json 파일, 로그인 시 받은 access_token을 보내고 발행한 카드 삭제를 요청합니다.
이 파일에는 삭제할 카드 ID, 카드를 발행한 주소, 핀 번호가 담겨 있습니다.
pin은 핀 번호(Klip Partners 회원 가입 시 설정한 6자리 숫자)를 해시()한 64자리 Hex String 값입니다.
