Luniverse's Multichain Web3 API is Chain Agnostic

Chain Agnostic API란?

Chain Agnostic API란, 특정 블록체인 네트워크를 위한 개별 인터페이스가 아닌 다수의 블록체인 네트워크에 공통적으로 사용 가능한 API를 의미합니다. 이를 통해 개발자는 각각 별도의 코드를 작성하지 않고도, 서로 다른 여러 블록체인 네트워크에 배포할 수 있는 분산형 어플리케이션을 보다 쉽게 구축할 수 있습니다.

최소한으로 구현하고, 빠르게 확장하세요.

Luniverse Multichain Web3 API는 Chain Agnostic API로 설계되었습니다. 분산형 어플리케이션 개발을 계획하고 계신가요? 특정 블록체인 프로토콜 또는 네트워크에 종속적인 구현은 어플리케이션의 확장성과 재사용성을 저해하는 요인입니다. 빠르게 변화하는 블록체인 시장에서, 환경의 변화에 유연하게 대응하고 확장하세요. 추상화된 인터페이스를 활용하면, 최소한의 구현으로 쉽게 여러 블록체인 네트워크를 지원할 수 있습니다.

블록체인의 한계를 뛰어 넘으세요.

한명의 개발자가 모든 블록체인 네트워크의 전문가가 되기는 어렵습니다. 각 네트워크에서 사용되는 도메인 용어와 개념을 정확하게 이해하고, 체계적으로 데이터를 다루기 위해서는 많은 노력이 필요합니다. 자산을 추적하고 어플리케이션의 효과를 측정하기 위한 데이터들은 어떻게 얻을 수 있을까요? 서로 다른 네트워크 환경의 Finality와 Locality를 고려하면서, 실시간으로 쌓이는 수많은 Public 네트워크 데이터들의 실시간 검색, 정렬, 집계를 위한 데이터 파이프라인을 구축해야 합니다. 비싸고, 오래걸리는 파이프라인 구축 대신, 루니버스 API들을 활용하여 쉽고 빠르게 블록체인 데이터들을 활용해보세요. 쉽고 저렴한 실시간 어플리케이션 운용이 가능합니다.

Domains & Usecases

Protocol/Network

• GET listSupportedProtocols
  • 사용가능한 모든 프로토콜-네트워크 목록을 조회할 수 있습니다.
• GET listSupportedNetwork
  • 특정 프로토콜에 대해 사용가능한 네트워크 목록을 조회할 수 있습니다.

Account(Wallet)

• GET listAccountBalance
  • 특정 계정 주소가 소유한 자산의 잔고 목록을 조회할 수 있습니다.
  • Native Token, 컨트랙트 자산(FT, NFT)의 잔고 조회를 지원합니다.
• POST listMultiAccountsBalance
  • 입력한 다수의 계정 주소가 소유하고 있는 Native Token 잔고를 목록으로 조회할 수 있습니다.
• GET listAccountTransactions
  • 특정 계정 주소로부터 전송되거나, 해당 계정 주소로 전송된 트랜잭션 목록을 조회할 수 있습니다.

Block/Transaction

• GET listBlocks
  • 대상 프로토콜-네트워크의 최근 N개 블록에 대한 정보를 조회합니다.
  • 최신 블록의 정보 및 블록 Index number를 확인할 수 있습니다.
• GET getBlockByHashOrNumber
  • 블록 해시(hash)값이나 Index number를 사용하여 특정 블록 정보를 조회합니다.
• GET listBlockTransactions
  • 특정 블록에 포함된 트랜잭션 목록을 조회합니다.
• GET getTransactionByHash
  • 트랜잭션의 해시(hash)값으로 특정 트랜잭션의 정보를 조회합니다.
• GET getGasPrice
  • 네트워크의 현재 Gas price정보를 조회합니다.
• GET getNextNonce
  • 특정 계정으로부터 다음 트랜잭션 생성하기 위해 사용 가능한 Nonce값을 조회합니다.

Transfer

• POST listTokenTransferByAccount
  • 특정 주소로부터 전송되거나 특정 주소로 전송된 토큰의 이력을 조회합니다.
• POST listTokenTransferByContract
  • 특정 컨트랙트 주소로부터 전송되거나 특정 컨트랙트 주소로 전송된 토큰의 이력을 조회합니다.
• POST listNftTransferByAccount
  • 특정 주소로부터 전송되거나 특정 주소로 전송된 NFT의 이력을 조회합니다.
• POST listNftTransferByContract
  • 특정 컨트랙트 주소로부터 전송되거나 특정 컨트랙트 주소로 전송된 NFT의 이력을 조회합니다.
• POST listNftTransferByTokenId
  • TokenId로 특정된 NFT의 전송 이력을 조회합니다.

Token

• POST listTokenBalanceByOwner
  • 특정 주소의 토큰 잔고를 조회합니다.
• POST listTokenBalanceByContract
  • 특정 컨트랙트의 주소를 입력하여 해당 컨트랙트가 보유한 토큰의 잔고를 조회합니다.
• POST getTokenAllowance
• Owner에게 권한을 받은 Spender가 제어할 수 있는 토큰의 수량을 조회합니다.
• POST listTokenMintByAccount
  • 특정 주소에 생성된 토큰의 목록을 조회합니다.
• POST listTokenMintByContract
  • 특정 컨트랙트 주소에 생성된 토큰의 목록을 조회합니다.
• POST listTokenBurnByAccount
  • 특정 주소에서 소각된 토큰의 목록을 조회합니다.
• POST listTokenBurnByContract
  • 특정 컨트랙트 주소에서 소각된 토큰의 목록을 조회합니다.
• POST listTokenMetadataBySymbols
  • 토큰의 Symbol을 이용하여 해당 토큰의 메타데이터를 조회합니다. Symbol은 배열로 입력하여 다중 조회할 수 있습니다.
• POST listTokenMetadataByContracts
  • 컨트랙트 주소를 이용하여 해당 토큰의 메타데이터를 조회합니다. 컨트랙트 주소는 배열로 입력하여 다중 조회할 수 있습니다.

NFT

• POST listNftByOwner
  • 특정 주소가 소유한 NFT에 대한 목록을 조회할 수 있습니다.
• POST listNftByContract
  • 특정 컨트랙트가 발행한 NFT 목록을 조회할 수 있습니다.
• POST listNftByOwnerAndContract
  • 특정 주소가 소유한 특정 컨트랙트에서 발행한 NFT 목록을 조회할 수 있습니다.
• POST listNftOwnerByContract
  • 특정 컨트랙트에서 발행한 NFT의 Owner 목록을 조회할 수 있습니다.
• POST getNftOwnerByTokenId
  • 특정 NFT의 Owner 주소를 조회할 수 있습니다.
• POST listNftContractMetadataByContract
  • 특정 NFT 컨트랙트의 Metadata를 조회할 수 있습니다.
  • 최대 10개의 NFT 컨트랙트 주소를 입력할 수 있습니다.
• POST listNftContractMetadataByOwner
  • 특정 주소가 소유한 NFT의 컨트랙트 메타데이터를 조회할 수 있습니다.
• POST searchNftByContractMetadataByKeyword
  • 특정 Keyword로 컨트랙트의 메타데이터를 검색할 수 있습니다.
    Keyword로 입력할 수 있는 값은 symbol, name 입니다.
• POST getNftMetadataByTokenId
  • TokenId를 이용하여 특정 NFT의 메타데이터를 조회할 수 있습니다.

Asset(Token, NFT)

• GET getAssetMetadata
  • 특정 자산 정보를 조회할 수 있습니다. 컨트랙트 기반 자산인 경우 컨트랙트 주소를 입력합니다.
  • Asset 도메인에 해당하는 정보가 반환됩니다.
• GET listNftAssetTokens
  • 특정 NFT 컨트랙트에서 발급된 토큰 목록을 조회할 수 있습니다.
• GET listAssetHolder
  • 특정 컨트랙트 자산의 모든 holder 계정 주소를 조회할 수 있습니다.
  • 필터 옵션을 사용하여, 특정 Non-Fungible Token(NFT)의 현재 소유 계정 주소를 조회할 수 있습니다.
  • 필터 옵션을 사용하여, 특정 계정 주소가 이 컨트랙트 자산의 holder인지 여부를 확인할 수 있습니다.
  • 필터 옵션을 사용하여, 특정 계정 주소가 이 컨트랙트에서 발행된 특정 토큰의 현재 holder인지 여부를 확인할 수 있습니다.

Event Logs

• GET searchEvent
  • 지정한 범위의 블록에서 발생한 특정 Event Log를 조회합니다.
  • Event 검색을 위해서는 해당 Event의 정의, 즉 Signature가 필요하기 때문에, 대상 컨트랙트의 ABI를 입력해야합니다.

Statistics

• GETlistAvailableStats
  • 현재 사용가능한 모든 통계 인터페이스 path 목록을 조회합니다.
• GETgetDailyTransactionStat
  • 특정 프로토콜-네트워크에서 발생한 일일 트랜잭션 수 통계를 조회합니다.
• GETgetHourlyTransactionStat
  • 특정 프로토콜-네트워크에서 발생한 시간별 트랜잭션 수 통계를조회합니다.
• GETgetDailyActiveAccountStat
  • 특정 프로토콜-네트워크의 일일 활성 계정 수 통계를 조회합니다.
• GETgetHourlyActiveAccountStat
  • 특정 프로토콜-네트워크의 시간별 활성 계정 수 통계를 조회합니다.
• GETgetDailyContractTransactionsStat
  • 특정 스마트 컨트랙트에 발생한 일일 트랜잭션 수 통계를 조회합니다.
• GETgetHourlyContractTransactionsStat
  • 특정 스마트 컨트랙트에 발생한 시간별 트랜잭션 수 통계를 조회합니다.
• GETgetDailyContractActiveAccountStats
  • 특정 스마트 컨트랙트에 대해 일일 활성 계정 수 통계를 조회합니다.
• GETgetHourlyContractActiveAccountStats
  • 특정 스마트 컨트랙트에 대해 시간별 활성 계정 수 통계를 조회합니다.

API Design

1. Path

루니버스 Multichain Web3 API의 Path는 공통적으로 아래와 같이 구성됩니다.

/{version}/{protocol}/{network}/{API resource}
//EXAMPLE: /v1/ethereum/mainnet/accounts

• version: API의 버전을 명시합니다. (예시) v1
• protocol: 호출 대상 블록체인 환경의 프로토콜을 명시합니다. 지원하는 체인 환경 및 사용 가능한 프로토콜 값은 Supported Chains 페이지를 참조하세요.
• network: 호출 대상 블록체인 환경의 네트워크를 명시합니다. 지원하는 체인 환경 및 사용 가능한 네트워크 값은 Supported Chains 페이지를 참조하세요.
• resource: 각 API의 리소스가 정의되는 파트로, 계층 구조로 구성됩니다.

2. Listing & Paging

API의 응답이 목록 형식의 데이터를 포함하는 경우 아래와 같이 count와 items항목을 활용하여 목록의 크기와 데이터를 구분하여 정의합니다. 또한 대부분의 목록 응답에 대해서는 Paging을 위한 Query Parameter 사용을 지원합니다. 자세한 파라미터 사용법에 대해서는 아래 테이블을 참고하세요.

3. Authorization

API 명세의 우측 예시 필수 헤더에 Authorization 헤더가 포함된 경우, 인증이 필요한 API입니다. JWT 인증 토큰을 활용한 Bearer 인증 방식을 사용합니다. 다음은 인증 방법에 대한 안내입니다.

How to Authorize API with API Key

1. 루니버스 콘솔 내 Environment 상세 화면의 API Key 탭에서 API 호출을 위한 API Key를 생성하세요.
2. Auth API 호출 시 1에서 발급받은 API Key값을 입력하여 인증 토큰을 발급하세요.
3. Authorization 헤더 값으로 'Bearer {JWT Token}'을 입력합니다. 발급받은 인증 토큰의 값이 TEMP_AUTH_TOKEN 문자열인 경우, API 호출 예시는 아래와 같습니다. (실제 인증 토큰은 JWT토큰 형식, 즉 더욱 길고 .로 구분된 문자열 형식입니다.)

curl --location --request GET 'https://{endpoint}//{version}/{protocol}/{network}/{API resource}' \
--header 'Authorization: Bearer TEMP_AUTH_TOKEN' \
--header 'Content-Type: application/json'

4. Response Format

모든 Multichain Web3 API의 응답은 정상 응답 여부와 상관 없이 code 필드를 포함합니다. 전체 응답 코드에 대한 명세는 Error Reference 페이지를 참조하세요.

정상 응답(HTTP 상태코드가 2XX인 경우)의 경우 응답 Body 내부에 data 필드를 포함하며, 해당 필드 내부에 실제 응답 객체가 도메인 응답의 형태로 반환됩니다.

정상 응답이 아닌 경우, message필드가 code필드와 함께 응답 내에 포함됩니다. 발생한 오류에 대한 설명을 포함합니다.

성공과 실패 각 케이스에 대한 응답 예시는 다음과 같습니다.

// Successful response with 2XX http status code
{
   "code":"SUCCESS",
   "data":{ --requested domain response will be included here-- }
}

// Error response
{
   "code":"RESOURCE_NOT_FOUND",
   "message":"Requested resource does not exist."
}