트랜잭션 API 개요

Solana 스왑 트랜잭션 빌더 서버입니다.

이 페이지는 AI 자동 번역입니다. 모든 내용은 영문판을 기준으로 합니다.

영문판 보기 →

​

트랜잭션 API란?

Raydium 트랜잭션 API (Route V2)는 클라이언트가 RPC 연결을 유지하거나 전체 Raydium SDK를 번들링할 필요 없이 직렬화된 Solana 스왑 트랜잭션을 빌드하는 서버 측 서비스입니다. 다음과 같은 통합을 크게 간소화합니다:

• 로컬 RPC 클라이언트를 실행할 수 없는 웹 프론트엔드
• 리소스가 제한된 모바일 애플리케이션
• 헤드리스 트레이딩 봇
• 애그리게이터 및 지갑 공급자

클라이언트에서 복잡한 풀 라우팅 및 트랜잭션 구성을 수행하는 대신, 우리 API에서 스왑 견적과 트랜잭션 빌딩을 요청한 후 모든 Solana RPC를 사용하여 결과에 서명하고 브로드캐스트합니다.

​

워크플로우 개요

트랜잭션 API는 관심사를 두 가지 단계로 분리합니다:

​

1. 계산 단계: 견적 받기

/compute/swap-base-in 또는 /compute/swap-base-out을 호출하여 현재 풀 상태에 따른 예상 스왑 출력 (또는 필요한 입력)을 받습니다. 이 엔드포인트는 읽기 전용이며 서명이 필요하지 않습니다:

GET /compute/swap-base-in?inputMint=EPjF...&outputMint=So111...&amount=1000000&slippageBps=50&txVersion=V0

응답에 포함되는 항목:

• 예상 출력 금액
• 라우트 분석 (사용되는 풀 및 유동성 소스)
• 가격 영향

​

2. 트랜잭션 단계: 빌드 및 서명

계산 응답을 받으면 이를 (지갑 및 구성과 함께) /transaction/swap-base-in 또는 /transaction/swap-base-out에 전달합니다:

POST /transaction/swap-base-in
Content-Type: application/json

{
  "wallet": "YourWalletAddress",
  "swapResponse": { ...response from /compute/swap-base-in },
  "txVersion": "V0",
  "computeUnitPriceMicroLamports": "1000",
  "wrapSol": false,
  "unwrapSol": false,
  "inputAccount": "TokenAccount1...",
  "outputAccount": "TokenAccount2..."
}

응답에 포함되는 항목:

• 서명할 준비가 된 Base64 인코딩된 버전화 트랜잭션
• 주소 조회 테이블 주소 (txVersion=V0인 경우)

클라이언트는 다음을 수행합니다:

1. 트랜잭션 디코딩
2. 사용자의 키페어로 서명
3. 모든 Solana RPC를 통해 브로드캐스트
4. 확인 대기

​

계산 엔드포인트

​

GET /compute/swap-base-in

사용 사례: 사용자가 입력 금액을 지정하면 출력을 계산합니다.

필수 쿼리 매개변수:

• inputMint – 보내는 토큰의 민트 주소
• outputMint – 원하는 토큰의 민트 주소
• amount – 입력 금액 (최소 단위인 라모포)
• slippageBps – 최대 허용 슬리피지 (기본점, 0–10000)
• txVersion – V0 또는 LEGACY

선택 사항:

• referrerBps – 리페러 권한이 있는 경우 리페러 수수료로 수집할 출력의 기본점

​

GET /compute/swap-base-out

사용 사례: 사용자가 원하는 출력을 지정하면 필요한 입력을 계산합니다.

필수 쿼리 매개변수:

• inputMint, outputMint, amount (원하는 출력), slippageBps, txVersion

참고: Base-out의 경우 리페러 기본점이 없습니다 (아직 구현되지 않음).

​

트랜잭션 엔드포인트

​

POST /transaction/swap-base-in

고정 입력 금액에 대한 트랜잭션을 빌드합니다.

필수 본문:

• wallet – 서명 지갑 주소
• swapResponse – 전체 계산 응답 객체
• txVersion – 트랜잭션 버전
• computeUnitPriceMicroLamports – 마이크로라모포 단위의 우선순위 수수료

선택 사항:

• wrapSol – true인 경우 입력을 위해 기본 SOL을 래핑합니다
• unwrapSol – true인 경우 출력에서 WSOL을 SOL로 언래핑합니다
• inputAccount – 입력용 토큰 계정 (SOL을 래핑하지 않는 경우 필수)
• outputAccount – 출력용 토큰 계정
• nonceInfo – 오프라인 서명을 위한 내구성 nonce
• jitoInfo – Jito MEV 보호 번들 매개변수
• referrerWallet – 수수료 수집을 위한 리페러 지갑

​

POST /transaction/swap-base-out

고정 출력 금액에 대한 트랜잭션을 빌드합니다.

Base-in과 동일한 매개변수, 단:

• referrerInfo 필드는 현재 주석 처리되어 있습니다 (아직 구현되지 않음)

​

응답 엔벨로프

모든 엔드포인트는 표준 엔벨로프를 반환합니다:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "success": true,
  "version": "V1",
  "data": { ... }
}

오류의 경우 success는 false이고 msg는 오류 코드를 포함합니다 (예: REQ_WALLET_ERROR, REQ_SLIPPAGE_BPS_ERROR).

​

트랜잭션 응답 형태

성공적인 트랜잭션 응답은 다음과 같습니다:

{
  "id": "...",
  "success": true,
  "version": "V1",
  "data": {
    "transaction": "AgABB...",
    "addressLookupTableAddresses": ["Address1...", "Address2..."]
  }
}

​

통합 예제

다음은 의사 코드의 일반적인 흐름입니다:

// 1. Get quote
const quote = await fetch(
  'https://transaction-v1.raydium.io/compute/swap-base-in?' +
  'inputMint=EPjF...&outputMint=So111...&amount=1000000&slippageBps=50&txVersion=V0'
).then(r => r.json());

// 2. Validate quote
if (!quote.success) {
  throw new Error(quote.msg);
}

// 3. Build transaction
const tx = await fetch(
  'https://transaction-v1.raydium.io/transaction/swap-base-in',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      wallet: userWalletAddress,
      swapResponse: quote,
      txVersion: 'V0',
      computeUnitPriceMicroLamports: '1000',
      inputAccount: userInputTokenAccount,
      outputAccount: userOutputTokenAccount,
    }),
  }
).then(r => r.json());

// 4. Decode and sign
const transaction = VersionedTransaction.deserialize(
  Buffer.from(tx.data.transaction, 'base64')
);
transaction.sign([userKeypair]);

// 5. Send via RPC
const rpc = new Connection('https://api.mainnet-beta.solana.com');
const sig = await rpc.sendTransaction(transaction);
await rpc.confirmTransaction(sig);

​

주요 매개변수 설명

​

txVersion

• V0: 주소 조회 테이블 (ALT)이 있는 최신 Solana 트랜잭션입니다. 더 작은 직렬화 크기, 낮은 수수료.
• LEGACY: ALT 이전 트랜잭션 형식입니다. 더 크지만 모든 RPC 엔드포인트에서 작동합니다.

가능할 때 V0를 선택하고, RPC 또는 지갑이 ALT를 지원하지 않으면 LEGACY로 폴백합니다.

​

computeUnitPriceMicroLamports

더 빠른 블록 포함을 위한 우선순위 수수료입니다. 우선순위 수수료가 없으려면 0으로 설정하거나, 혼잡한 네트워크에서 경쟁하기 위해 더 높은 값 (예: 1000)으로 설정합니다. 단위는 컴퓨트 유닛당 마이크로라모포입니다.

​

slippageBps

기본점 단위의 최대 슬리피지 허용량입니다. 100 = 1%, 50 = 0.5%.

• 대부분의 안정적인 스왑의 경우 더 낮은 값 (예: 25–50 bps) 사용
• 변동성이 크거나 유동성이 낮은 쌍의 경우 증가

​

wrapSol 및 unwrapSol

• wrapSol: true인 경우 API가 기본 SOL을 WSOL로 래핑합니다. inputAccount가 필요하지 않습니다.
• unwrapSol: true인 경우 API가 출력 WSOL을 기본 SOL로 언래핑합니다. outputAccount가 필요하지 않습니다.

둘 다 false인 경우 명시적 토큰 계정을 제공해야 합니다.

​

네트워크 엔드포인트

네트워크	메인넷	데브넷
호스트	transaction-v1.raydium.io	transaction-v1-devnet.raydium.io
프로토콜	HTTPS	HTTPS

​

오류 코드

일반적인 오류 메시지:

코드	의미
REQ_SLIPPAGE_BPS_ERROR	슬리피지가 유효하지 않거나 범위를 벗어남
REQ_INPUT_MINT_ERROR	입력 민트 주소가 유효하지 않음
REQ_OUTPUT_MINT_ERROR	출력 민트 주소가 유효하지 않음
REQ_AMOUNT_ERROR	금액이 유효한 숫자가 아님
REQ_TX_VERSION_ERROR	txVersion은 V0 또는 LEGACY여야 함
REQ_WALLET_ERROR	지갑 주소가 유효하지 않음
REQ_INPUT_ACCOUT_ERROR	입력 토큰 계정이 누락되었거나 유효하지 않음
REQ_OUTPUT_ACCOUT_ERROR	출력 토큰 계정이 누락되었거나 유효하지 않음
UNKNOWN_ERROR	서버 측 오류입니다. 요청 매개변수를 확인하세요

​

참고 자료

• OpenAPI 사양
• 애그리게이터 통합 가이드