XRP Ledger Quickstart

XRPL(XRP Ledger)은 글로벌 결제 및 기업용 애플리케이션 구축을 위해 설계된 오픈소스 분산형 블록체인으로, 고유한 XRP Ledger 합의 프로토콜을 통해 높은 성능과 낮은 수수료, 지속 가능한 네트워크를 제공합니다. 트랜잭션 처리 시 최적의 환전 경로를 찾아주는 Pathfinding과, 다자간 효과적인 자산 교환을 위한 Rippling, 법정화폐나 디지털 자산을 XRPL 위에서 토큰화하기 위한 IOU 등 자산의 발행과 전송에 특화된 기능을 지원합니다.

↗ 공식사이트: XRPL

↗ Explorer: XRP Scan

↗ Faucet: XRPL Testnet Faucet

🎉
XRPL Web3 Data API를 지금 사용해보세요!
Nodit Web3 Data API가 XRPL 네트워크를 새롭게 지원합니다.
유료플랜 사용자라면 지금 바로 Web3 Data API API Reference를 확인하고 사용해보세요!

Feature	Mainnet Support	Testnet Support
Elastic Node	❌	❌
Dedicated Node	❌	❌
Web3 Data API	✅	❌
Webhook	❌	❌
Stream	❌	❌
Datasquare	❌	❌

Understanding the XRPL Data Model in Nodit

Our Approach

XRPL는 다른 블록체인 네트워크 프로토콜들과 구별되는 고유한 트랜잭션 타입, 토큰 표준(IOU) 및 토큰/자산 교환 방식(Pathfinding, Rippling)를 지원하여 데이터의 복잡도가 높습니다. Nodit의 XRPL Web3 Data API는 이러한 복잡도를 최소화하여, XRPL의 주요 Usecase인 Transaction, Token Transfer, Asset Balance 변경 이력 등의 데이터를 이해하기 쉽게 제공합니다.

Ledger vs. Block

XRPL에서는 일반적인 블록체인의 "Block" 대신 "Ledger"라는 용어를 사용합니다. 두 개념은 모두 트랜잭션 묶음을 기록하고 이전 단위와 연결된다는 점에서 유사하지만, 의미와 구조는 약간 다릅니다. 일반적인 블록체인 네트워크에서의 Block이 트랜잭션 목록 중심의 단위인 반면, XRPL의 Ledger는 트랜잭션 결과가 반영된 네트워크의 전체 상태를 포함하는 단위입니다. 각 Ledger는 고유한 ledger index와 ledger hash를 가지며, 연속된 상태 변화의 흐름을 형성합니다.

Nodit은 이러한 프로토콜 차이를 반영하여, XRPL 데이터에서는 일관되게 Ledger라는 용어를 사용합니다.

XRPL Transaction Structure

XRPL 트랜잭션은 크게 네 부분으로 구성됩니다.

공통 필드(Common Fields)
모든 트랜잭션에 공통으로 포함되는 기본 정보로, 거래를 제출한 계정(Account), 지불 수수료(Fee), 계정의 시퀀스 번호(Sequence), 서명에 사용된 공개키(SigningPubKey), 이 트랜잭션이 유효할 마지막 Ledger index등을 제공합니다.
트랜잭션 타입(Transaction Types)
트랜잭션의 목적에 따라 구분되는 유형으로, Payment, OfferCreate, EscrowCreate 등 다양한 각 타입에 대해 타입별 필수(required) 필드와 선택(optional) 필드가 다르게 정의됩니다.
트랜잭션 결과(Transaction Results)
트랜잭션 처리 후 실행 상태를 나타내며, 성공·실패 여부와 오류 원인을 제공합니다.
트랜잭션 메타데이터(Transaction Metadata)
Ledger에 트랜잭션을 적용하면서 발생한 상태 변경 정보를 기록합니다. 이 정보는 "metadata.affectedNodes" 필드에 담기며, 여기서 각 Entry는 Ledger의 특정 노드에 대한 상태 변화를 나타냅니다. 자산 이동의 주요 Entry 유형은 다음과 같습니다.
- AccountRoot Entry: 네이티브 토큰(XRP) 잔고 변화 기록
- RippleState Entry: IOU 토큰 Trust Line 상태 변화 및 해당 토큰의 잔고 변화 기록

XRPL Transaction Structure in Nodit

Transaction Categorization

데이터 복잡도를 낮추고 필드 분류를 용이하게 하기 위해, XRPL의 트랜잭션 유형을 그대로 사용하지 않고 카테고리(Category) 필드로 묶어 구분합니다. 각 카테고리 별로 맵핑되는 XRPL 트랜잭션 유형은 아래 표와 같습니다.

Transaction Category (in Nodit)	Transaction Types
AMM	`AMMBid`, `AMMClawback`, `AMMCreate`, `AMMDelete`, `AMMDeposit`, `AMMVote`, `AMMWithdraw`
Check	`CheckCreate`, `CheckCash`, `CheckCancel`
Escrow	`EscrowCreate`, `EscrowCancel`, `EscrowFinish`
Offer	`OfferCreate`, `OfferCancel`
Payment	`Payment`
Payment Channel	`PaymentChannelCreate`, `PaymentChannelFund`, `PaymentChannelClaim`

공통 필드와 TransactionDetails 필드

Nodit Web3 Data API는 트랜잭션 유형별 세부 정보들을 API 응답 내 TransactionDetails객체로 묶어 반환합니다. 이를 통해 모든 트랜잭션에 대해 공통으로 분석 가능한 데이터 영역과, 트랜잭션 유형에 따라 별도 분석 가능한 데이터 영역을 구분하여 처리할 수 있습니다.

IOU Token

IOU(I owe you) 토큰은 XRPL에서 네이티브 토큰(XRP) 외에 발행자가 지정한 자산을 나타내는 방식입니다. XRPL 정책에 따라 중복된 통화 코드(currency)로의 IOU 발행이 가능하기 때문에, 각 IOU 토큰은 통화 코드와 토큰 발행자(issuer)의 조합으로 고유하게 식별됩니다.

XRPL Node API를 통해 IOU 토큰의 전송 내역 또는 잔고 변화 이력을 조회하기 위해서는 각 트랜잭션 Metadata의 Affected Nodes 필드를 각각 분석하고 이들의 RippleState Entry를 모두 비교하며 추적해야 하는 어려움이 있었습니다. Nodit의 XRPL Web3 Data API를 사용하면 통화 코드와 토큰 발행자로 해당 토큰의 전송 이력과 잔고 증감 내역을 쉽게 조회할 수 있습니다.

Balance Change

Balance Change는 XRPL 메타데이터의 AccountRoot Entry와 RippleState Entry를 기반으로 가공된 데이터를 제공하며, 다음 세 가지 값을 포함한 각 계정의 잔고 변동 기록을 반환합니다.

previousBalance: 변동 이전 잔고
finalBalance: 변동 이후 잔고
balanceChange: 변화량

Token Transfer

XRPL에서는 하나의 토큰 전송에 송신자와 수신자외의 여러 중간자가 포함될 수 있습니다. 모든 토큰 전송은 항상 토큰 발행자인 게이트웨이를 통해 기록되어야 하는 특성과, Pathfinding 및 Rippling과 같은 고유의 토큰 전송 구조 때문입니다.

Nodit XRPL Web3 Data API에서는 하나의 토큰 전송건에 포함된 여러 부분 전송건 각각을 토큰 전송 이력으로 반환합니다. 이를 활용하여 단순 송금 이력에 대한 분석 뿐 아니라, 잔고 변동 기록 분석으로는 알기 어려운 다수의 계정과 게이트웨이를 거치는 복잡한 리플(Ripple) 전송 과정 등을 효과적으로 분석할 수 있습니다.

Web3 Data API

Token API

Native Token API

Blockchain API

Example

특정 계정에 대한 IOU Token 관련 전송 목록을 Get Token Transfers by Account을 통해서 조회

Request

Node.js - axios

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://web3.nodit.io/v1/xrpl/mainnet/token/getTokenTransfersByAccount',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    'X-API-KEY': '{YOUR_API_KEY}'
  },
  data: {
    accountAddress: 'rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah',
    currency: 'USD',
    issuer: 'rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq',
    fromDate: '2025-01-01T00:00:00+00:00',
    toDate: '2025-01-31T00:00:00+00:00',
    withCount: false
  }
};

axios
  .request(options)
  .then(res => console.log(res.data))
  .catch(err => console.error(err));

Python - requests

import requests

url = "https://web3.nodit.io/v1/xrpl/mainnet/token/getTokenTransfersByAccount"

payload = {
    "accountAddress": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
    "currency": "USD",
    "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
    "fromDate": "2025-01-01T00:00:00+00:00",
    "toDate": "2025-01-31T00:00:00+00:00",
    "withCount": False
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "X-API-KEY": "{YOUR_API_KEY}"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Response

{
  "rpp": 20,
  "cursor": "eyJsZWRnZXJJbmRleCI6OTMxNzA0MTksInRyYW5zYWN0aW9uSW5kZXgiOjI5LCJ0cmFuc2FjdGlvbk1ldGFJbmRleCI6MywidHJhbnNhY3Rpb25NZXRhU3ViSW5kZXgiOjB9",
  "items": [
    {
      "ledgerIndex": 93173022,
      "ledgerTimestamp": 1735766671,
      "transactionIndex": 110,
      "transactionHash": "DA528CDD2CE2FB22A466E2EF64F26779179A73E978A2F78372D32FAAAF71E408",
      "transactionType": "OfferCreate",
      "affectedNodesIndex": 1,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "68.32665958138695"
    },
    {
      "ledgerIndex": 93173020,
      "ledgerTimestamp": 1735766661,
      "transactionIndex": 67,
      "transactionHash": "06061E0FD844B0137C22216FDEFC76DB9E41C99885533EBCADA0D5CEA0133383",
      "transactionType": "OfferCreate",
      "affectedNodesIndex": 1,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "45.97409537496615"
    },
    {
      "ledgerIndex": 93173017,
      "ledgerTimestamp": 1735766651,
      "transactionIndex": 185,
      "transactionHash": "4BC811C88AF33D24E878ADDD086925B57395D49E727B112E65A87BEC7B8678B4",
      "transactionType": "OfferCreate",
      "affectedNodesIndex": 1,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "223.6109914402623"
    },
    {
      "ledgerIndex": 93173017,
      "ledgerTimestamp": 1735766651,
      "transactionIndex": 179,
      "transactionHash": "F1EDB348C372DD33AC3D7C136979F69A7ECE6DCDD7DD5CCA7F2C4993E692CF57",
      "transactionType": "OfferCreate",
      "affectedNodesIndex": 2,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "15.2464766247965"
    },
    {
      "ledgerIndex": 93173013,
      "ledgerTimestamp": 1735766632,
      "transactionIndex": 105,
      "transactionHash": "7D9916CB45A1BDCFFAFFBC258A5064FCFE08BE6991CD619431B52F8921889F72",
      "transactionType": "OfferCreate",
      "affectedNodesIndex": 2,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "14.0871346637655"
    },
    {
      "ledgerIndex": 93172996,
      "ledgerTimestamp": 1735766570,
      "transactionIndex": 14,
      "transactionHash": "45B71819ABA88B43E3A2EAF29CAD9B918D209F17B9DB37E1BD8826A885691864",
      "transactionType": "OfferCreate",
      "affectedNodesIndex": 2,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "16.0249390527976"
    },
    {
      "ledgerIndex": 93172990,
      "ledgerTimestamp": 1735766541,
      "transactionIndex": 140,
      "transactionHash": "B2DC0ED768A7A230F6400A3D5F9AA4440392CE861CA87C522B788393A25B62A3",
      "transactionType": "OfferCreate",
      "affectedNodesIndex": 3,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "11.2998736439995"
    },
    {
      "ledgerIndex": 93172975,
      "ledgerTimestamp": 1735766481,
      "transactionIndex": 68,
      "transactionHash": "BB59BCC004DA2E694E9C7332DF5B6FE8832D3528A68C5DB7D3596FD91FE8307E",
      "transactionType": "OfferCreate",
      "affectedNodesIndex": 3,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "9.7755348214093"
    },
    {
      "ledgerIndex": 93172973,
      "ledgerTimestamp": 1735766472,
      "transactionIndex": 65,
      "transactionHash": "B0AF10C8F47CC7574DD9AA9629BE5E86281ED1CEF3EB2B27B041CB047020E84E",
      "transactionType": "Payment",
      "affectedNodesIndex": 1,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "12.59571071884"
    },
    {
      "ledgerIndex": 93171689,
      "ledgerTimestamp": 1735761451,
      "transactionIndex": 41,
      "transactionHash": "1937B143BF7AA399155D589D9CE51D2A5BD8D2280771BE8C97CD6D71F169F257",
      "transactionType": "OfferCreate",
      "affectedNodesIndex": 1,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "96.8328331581"
    },
    {
      "ledgerIndex": 93171687,
      "ledgerTimestamp": 1735761442,
      "transactionIndex": 19,
      "transactionHash": "2A2AAE7F772E888655BE8C079A8F77833651DC290DC663B6377203155F809D34",
      "transactionType": "OfferCreate",
      "affectedNodesIndex": 1,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "349.6662716805774"
    },
    {
      "ledgerIndex": 93171034,
      "ledgerTimestamp": 1735758881,
      "transactionIndex": 8,
      "transactionHash": "15718AC85CF3B615B202BE9F23470D007B287C3BB20AF11331FE4183E539B65D",
      "transactionType": "Payment",
      "affectedNodesIndex": 1,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "1.591614187843"
    },
    {
      "ledgerIndex": 93171029,
      "ledgerTimestamp": 1735758861,
      "transactionIndex": 93,
      "transactionHash": "FAB0856D35FB84010DA81DBCB5B4BF7439B71BE738D6A61C956826AE127C7A15",
      "transactionType": "Payment",
      "affectedNodesIndex": 1,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "0.0757475058994"
    },
    {
      "ledgerIndex": 93171014,
      "ledgerTimestamp": 1735758802,
      "transactionIndex": 4,
      "transactionHash": "A9214E46735BA0821E28BD16C63A3E11446523D795867AECC4D846AF33CD3618",
      "transactionType": "Payment",
      "affectedNodesIndex": 2,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "0.4090565140283"
    },
    {
      "ledgerIndex": 93171013,
      "ledgerTimestamp": 1735758801,
      "transactionIndex": 73,
      "transactionHash": "F72D5A793806EBC1B6377CE022CB1CDE831A6B376A4DB6A136D90234B383D534",
      "transactionType": "Payment",
      "affectedNodesIndex": 1,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "0.1647904946749"
    },
    {
      "ledgerIndex": 93170749,
      "ledgerTimestamp": 1735757771,
      "transactionIndex": 118,
      "transactionHash": "CB9FE626B763A63C270B8368C6611282481060D8CF0011866D3E47A24975ACE1",
      "transactionType": "OfferCreate",
      "affectedNodesIndex": 3,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "88.539571219593"
    },
    {
      "ledgerIndex": 93170605,
      "ledgerTimestamp": 1735757210,
      "transactionIndex": 75,
      "transactionHash": "811FBD040321A2B2F7186C2AA77368055C08B6930585A3189E720209F055D542",
      "transactionType": "OfferCreate",
      "affectedNodesIndex": 3,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "42.4292961514766"
    },
    {
      "ledgerIndex": 93170425,
      "ledgerTimestamp": 1735756501,
      "transactionIndex": 66,
      "transactionHash": "B37159FB812FB6A499DB57878A7A8E30A687C91612CC4BC0AEEE1CB85C77EA9E",
      "transactionType": "OfferCreate",
      "affectedNodesIndex": 2,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "15.0226464352986"
    },
    {
      "ledgerIndex": 93170420,
      "ledgerTimestamp": 1735756481,
      "transactionIndex": 71,
      "transactionHash": "F55A9ED2AF89A4CD1A7ECC271A619BB76494FF1CD9B3685F41FC70E792486175",
      "transactionType": "Payment",
      "affectedNodesIndex": 1,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "0.735321001233"
    },
    {
      "ledgerIndex": 93170419,
      "ledgerTimestamp": 1735756480,
      "transactionIndex": 29,
      "transactionHash": "D1BCE77569D6F8EFB992675685525E23B2C484C2D7E45175100F50C9EC3A2088",
      "transactionType": "OfferCreate",
      "affectedNodesIndex": 3,
      "from": "rBTwLga3i2gz3doX6Gva3MgEV8ZCD8jjah",
      "to": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
      "currency": "USD",
      "value": "2.225607044411"
    }
  ]
}

🎉XRPL Web3 Data API를 지금 사용해보세요!

Understanding the XRPL Data Model in Nodit

Our Approach

Ledger vs. Block

XRPL Transaction Structure

XRPL Transaction Structure in Nodit

Transaction Categorization

공통 필드와 TransactionDetails 필드

IOU Token

Balance Change

Token Transfer

Web3 Data API

Token API

Native Token API

Blockchain API

Example

Request

Response

🎉
XRPL Web3 Data API를 지금 사용해보세요!