Guides

Lab2. Retrieve Account Asset Balances

이번 Lab에서는 이더리움 네트워크에서 계정의 자산 잔고를 조회하는 방법을 배웁니다. ETH를 비롯한 다양한 유형의 자산을 조회하기 위해 루니버스 Multichain API를 활용합니다.

Suggest Edits

Lab Overview

Lab2에서는 다음과 같은 작업을 수행합니다:

  1. API 이해도 향상: Account API에 대한 더 깊은 이해를 돕기 위해 먼저 API의 기능과 엔드포인트를 학습합니다.
  2. 자산 잔고 출력 코드 구현: API Docs를 참고하여 자산 잔고를 출력하는 코드를 완성합니다.
  3. 프로젝트에 반영 확인: 작성한 코드가 실제 프로젝트에 반영되어 동작 하는지 확인합니다. 특정 계정을 검색하여 이더리움(ETH) 잔고 및 NFT 잔고 조회 결과를 확인합니다.

이번 Lab을 완료하면 계정의 자산 잔고를 조회하는 방법을 익힐 수 있습니다.



Prerequisites

이번 랩을 진행하기 위해서는 아래의 작업을 완료해야 합니다:

  1. [Lab1. Generate Authentication Tokens]을 완료했어야 합니다. 인증 토큰은 Multichain API를 사용하기 위한 필수 요소입니다. 인증 토큰을 생성하지 않았다면, 먼저 Lab1을 완료하세요.
  2. 루니버스 콘솔에서 Node ID와 API Key 정보를 생성하고 안전한 곳에 보관해야 합니다. Node ID, API Key ID, 그리고 API Key Secret은 Multichain API를 호출하는 데 필요한 정보입니다.

위의 작업을 완료하셨다면, 이제 Lab2로 진행할 준비가 되었습니다!



사용할 API 살펴보기

일반적으로 이더리움에서 계정의 자산 잔고를 조회하려면 어떻게 해야 할까요? 기본적으로 제공되는 JSON-RPC 메서드 중 eth_getBalance 메서드를 사용하면 자산을 확인할 수 있습니다. 그러나 이 방법은 오직 ETH 잔고만 조회할 수 있습니다. ERC-20, ERC-721과 같은 표준 규격을 따르는 자산의 경우, 각각의 컨트랙트에 eth_call 메서드를 사용하여 잔고를 조회해야 합니다. 또한, 어떤 컨트랙트가 어떤 자산을 보유하고 있는지를 알 수 없기 때문에 모든 토큰 컨트랙트에 대해 조회 과정을 반복해야 합니다. 이는 상당한 시간과 자원을 소모하는 작업이 될 수 있습니다..

하지만, 루니버스 Mulitchain API를 이용하면 간단한 API 호출로 손쉽게 자산 정보를 얻을 수 있습니다. 이번 세션에서는 listAccountBalance API를 활용하여 계정의 자산 조회하는 방법을 배워보겠습니다.

listAccountBalance

listAccountBalance를 사용하면 특정 계정의 자산 잔고 목록을 조회할 수 있습니다. 이 API는 쿼리 파라미터를 지정하지 않으면 네이티브 토큰의 잔고를 반환합니다. 다른 자산 유형이나 특정 컨트랙트의 자산을 조회하려면 type 파라미터를 사용할 수 있습니다.

자산의 유형 (type)

이 API는 자산의 유형을 세 가지로 구분 하여 잔고를 조회합니다. 원하는 유형을 쿼리 파라미터로 입력하면 해당 유형의 잔고 목록을 조회할 수 있습니다. 만약 아무 유형도 입력하지 않으면 네이티브 토큰의 잔고를 반환합니다.

  1. native: 호출하는 네트워크의 네이티브 토큰(e.g., 이더리움의 경우, ETH)의 잔고를 반환합니다.
  2. nft: 계정이 보유한 Non-Fungible Token(ERC-721, ERC-1155)의 잔고 목록을 반환합니다.
  3. ft: 계정이 보유한 Fungible Token(ERC-20)의 잔고 목록을 반환합니다.

컨트랙트 주소 (contract)

만약 모든 자산 목록이 아닌 특정 컨트랙트에서 발행된 잔고만 조회하고 싶다면, 파라미터에 contract 주소를 지정하면 됩니다. (단, contract 파라미터는 native token은 컨트랙트 주소가 없기 때문에 자산 유형을 ft, nft 로 선택한 경우에만 사용할 수 있습니다.)

더 자세한 내용은 listAccountBalance API docs를 참고하세요!



적용해보기

Luniverse Instance

  • 파일 경로: [ server > src > apis > instances.ts ]

server 폴더 안의 instances.ts 파일을 열어주세요. 이 파일에는 루니버스 Multichain API에 호출할 때 필요한 인스턴스인 luniverseInstance가 정의되어 있습니다. luniverseInstance 에는 우리가 호출하고자 하는 API의 base URL과 인증 토큰(AUTH_TOKEN)에 대한 정보를 담고 있습니다.

📘

원하는 네트워크를 사용하려면 어떻게 해야 하나요?

instance.ts 파일에 있는 변수 PROTOCOL과 NETWORK에 원하는 프로토콜과 네트워크 값으로 변경하면 됩니다. 단, 이때 변경한 프로토콜과 네트워크과 대응하는 노드가 필요합니다. (해당 노드가 없다면 가이드 문서를 참조해 노드를 생성해 주시기 바랍니다.) 추가적으로, 변경한 노드에서 발급받은 인증토큰을 .env 파일의 AUTH_TOKEN에 입력해야 합니다.

instance.ts 파일에서 PROTOCOL과 NETWORK 변수를 원하는 프로토콜 및 네트워크 값으로 변경하세요. 단, 변경한 프로토콜과 네트워크에 해당하는 노드가 필요합니다. (해당 노드가 없는 경우, 가이드 문서를 참조하여 노드를 생성하세요.) 또한 변경한 노드에서 발급된 인증 토큰을 .env 파일의 AUTH_TOKEN에 입력해야 합니다.


lab2.ts

  • 파일 경로: [ server > src > apis > lab2.ts ]

이 파일에는 listAccountBalance API를 호출하는 함수가 정의되어 있습니다. 이 API를 호출할 때 필요한 정보들을 하나씩 채워볼까요?

미완성 코드

// server/src/apis/lab2.ts

import { luniverseInstance } from "./instances";

export async function listAccountBalance(
	address: string,
	type?: string,
	page?: number,
	rpp?: number,
	contract?: string
) {
	return luniverseInstance.request({
		// Complete here!
		method: "",
		url: ``,
		params: {},
	});
}

미완성 코드 중 비어있는 필드에 들어갈 알맞은 값을 API 문서를 참고하여 채워주세요!

  • method: HTTP 요청 메서드를 입력하는 필드입니다. 이 API는 "GET" 요청을 받습니다.
  • url: API 엔드포인트를 입력하는 곳입니다. luniverseInstance의 baseURL이 이미 설정되어 있으므로 나머지 엔드포인트 부분만 입력하면 됩니다. 따라서 url에는 /account/${address}/balance 를 입력합니다.
  • params: 쿼리 파라미터를 입력하는 곳입니다. 이 API는 type, page, rpp, contract 네 가지 쿼리 파라미터를 받습니다.

완성된 코드

위의 가이드를 따라 코드를 완성하면 아래와 같이 됩니다.

// server/src/apis/lab2.ts

import { luniverseInstance } from "./instances";

export async function listAccountBalance(
    address: string,
    type?: string,
    page?: number,
    rpp?: number,
    contract?: string
) {
    return luniverseInstance.request({
        // Complete here!
        method: "get",
        url: `/accounts/${address}/balance`,
        params: {
            type,
            page,
            rpp,
            contract,
        },
    });
}

코드를 모두 완성하셨나요? 다시 브라우저로 돌아가서 새로고침을 눌러보세요. 잔고 보드(Balance Board)가 실제 잔고 값으로 변경 되었다면 성공적으로 코드를 완성한 것입니다.

이제 여러분은 listAccountBalance API를 이용하여 모든 유형의 자산 잔고를 조회할 수 있게 되었습니다!

다음 랩에서는 NFT API에 대해 알아보고, 이를 활용하여 NFT 잔고와 NFT 메타데이터를 조회하는 방법을 배우게 될 것입니다. NFT API를 사용해보고 싶다면 다음 랩으로 이동하세요!

Updated about 1 year ago