SPL Token CLI 레퍼런스

spl-token 명령줄 인터페이스는 민트, token account, 권한, 전송, Token-2022 확장 기능을 생성하고 관리합니다.

이 레퍼런스는 Agave v4.2.1에 포함된 spl-token-cli v5.6.1 버전을 기준으로 합니다. spl-token --version을 실행하고, 설치된 버전에서 사용할 수 있는 정확한 옵션은 <command> --help로 확인하십시오.

민트 생성, 전송, 권한 변경, 소각, 동결, 계정 종료는 트랜잭션을 제출합니다. 명령을 실행하기 전에 클러스터, Token Program, 서명자, 주소를 확인하십시오. 메인넷에서의 변경은 실제 자산에 영향을 줍니다.

설치 및 도움말 확인

Agave CLI 릴리스 번들에는 spl-token이 포함되어 있습니다. 설치되어 있지 않다면 게시된 Rust crate를 사용하십시오:

cargo install spl-token-cli --version 5.6.1
spl-token --version

루트 또는 명령 수준에서 도움말을 확인합니다:

spl-token --help
spl-token create-token --help
spl-token transfer --help

전역 옵션

전역 옵션은 명령 앞에 배치합니다.

옵션	용도
`-u, --url <URL_OR_MONIKER>`	RPC URL 또는 `mainnet-beta`, `testnet`, `devnet`, `localhost` 중 하나를 선택합니다.
`-C, --config <PATH>`	다른 Solana CLI 설정 파일을 사용합니다.
`--fee-payer <KEYPAIR>`	트랜잭션 수수료를 지불할 계정을 선택합니다.
`-p, --program-id <ADDRESS>`	명시적인 Token Program ID를 사용합니다.
`--program-2022`	Token-2022(`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`)를 사용합니다.
`--output <FORMAT>`	지원되는 경우 `json` 또는 `json-compact`를 반환합니다.
`--with-compute-unit-limit <UNITS>`	트랜잭션의 컴퓨트 유닛 한도를 설정합니다.
`--with-compute-unit-price <MICRO_LAMPORTS>`	컴퓨트 유닛당 우선순위 가격을 설정합니다.
`-v, --verbose`	추가 출력을 표시합니다.
`-V, --version`	설치된 CLI 버전을 출력합니다.

기본 프로그램은 기존 Token Program입니다. Token-2022 민트 또는 계정에는 조회할 때를 포함하여 --program-2022를 사용하십시오. 선택한 프로그램이 제공된 주소를 소유하지 않으면 명령이 실패합니다.

토큰 생성 및 사용

명령은 생성된 주소를 출력합니다. create-token이 반환한 민트 주소를 저장해 두었다가 이후 명령에 사용하십시오.

# Create a six-decimal mint under the original Token Program.
spl-token --url devnet create-token --decimals 6

# Create the default signer's associated token account for the mint.
spl-token --url devnet create-account <MINT_ADDRESS>

# Mint 100 tokens to that associated token account.
spl-token --url devnet mint <MINT_ADDRESS> 100

# Read supply, balance, and complete mint or account details.
spl-token --url devnet supply <MINT_ADDRESS>
spl-token --url devnet balance <MINT_ADDRESS>
spl-token --url devnet display <MINT_OR_TOKEN_ACCOUNT_ADDRESS>

# Transfer tokens to a wallet and create its associated account if needed.
spl-token --url devnet transfer \
  <MINT_ADDRESS> \
  10 \
  <RECIPIENT_WALLET_ADDRESS> \
  --fund-recipient

금액은 민트의 소수점 자릿수(decimals)를 반영한 UI 토큰 수량입니다. transfer, burn, unwrap-sol 같은 명령은 도움말에 표시된 경우 ALL을 허용합니다.

Token-2022 민트 생성

확장 기능은 추가 민트 또는 계정 상태를 할당하며, 보통 민트를 생성할 때 선택해야 합니다. 다음 예제는 내장 메타데이터를 지원하는 소수점 6자리 민트를 생성합니다:

spl-token --program-2022 create-token \
  --decimals 6 \
  --enable-metadata

spl-token --program-2022 initialize-metadata \
  <MINT_ADDRESS> \
  "Example Token" \
  EXAMPLE \
  https://example.com/token.json

일반적인 create-token 확장 옵션은 다음과 같습니다:

--enable-close
--enable-confidential-transfers auto|manual
--enable-freeze
--enable-group 및 --enable-member
--enable-metadata
--enable-non-transferable
--enable-pause
--enable-permanent-delegate
--enable-permissioned-burn
--enable-transfer-hook 또는 --transfer-hook <PROGRAM_ID>
--interest-rate <BASIS_POINTS>
--transfer-fee-basis-points <BASIS_POINTS>와 --transfer-fee-maximum-fee <AMOUNT>
--ui-amount-multiplier <MULTIPLIER>

Token-2022 프로그램이 함께 사용하도록 허용하는 확장 기능만 조합하십시오. 되돌릴 수 없는 민트 구성을 만들기 전에 관련 Token-2022 확장 기능 가이드를 검토하십시오.

권한 및 위임자 관리

# Change the mint authority.
spl-token authorize <MINT_ADDRESS> mint <NEW_AUTHORITY_ADDRESS>

# Permanently remove the mint authority.
spl-token authorize <MINT_ADDRESS> mint --disable

# Let a delegate spend up to 25 tokens from one token account.
spl-token approve \
  <TOKEN_ACCOUNT_ADDRESS> \
  25 \
  <DELEGATE_ADDRESS>

# Remove the current delegate.
spl-token revoke <TOKEN_ACCOUNT_ADDRESS>

authorize는 민트, 동결, 소유자, 종료 및 확장 기능별 권한 유형을 지원합니다. --disable로 권한을 제거하면, 다른 프로그램 메커니즘으로 복구할 수 없는 경우 영구적으로 제거됩니다.

동결, 소각, 종료

spl-token freeze <TOKEN_ACCOUNT_ADDRESS>
spl-token thaw <TOKEN_ACCOUNT_ADDRESS>

spl-token burn <TOKEN_ACCOUNT_ADDRESS> 5

# A token account must normally have a zero token balance before closing.
spl-token close --address <TOKEN_ACCOUNT_ADDRESS>

burn은 계정 잔액과 총 공급량을 모두 줄입니다. close는 계정에 남은 lamport를 설정된 수령인에게 반환하며, 소각된 토큰을 복구하지는 않습니다.

SOL 래핑 및 언래핑

# Create or fund the owner's wrapped SOL token account.
spl-token wrap 1

# Unwrap part of the wrapped SOL balance.
spl-token unwrap-sol 0.25

# Close the wrapped SOL account and return its full lamport balance.
spl-token unwrap

래핑된 SOL token account에 lamport를 직접 전송한 후에는 sync-native를 사용하여 토큰 수량을 기초 lamport와 일치시키십시오.

멀티시그 서명

최대 11명의 구성원으로 구성된 M-of-N Token Program 멀티시그를 생성합니다:

spl-token create-multisig \
  2 \
  <MEMBER_1_ADDRESS> \
  <MEMBER_2_ADDRESS> \
  <MEMBER_3_ADDRESS>

해당 멀티시그가 제어하는 트랜잭션에는 멀티시그 주소를 관련 권한으로 전달하고, 반복되는 --multisig-signer 값으로 구성원 keypair를 제공하십시오. 주 권한 플래그는 작업마다 다르므로 대상 명령의 도움말을 확인하십시오.

기밀 잔액

기밀 잔액 명령에는 기밀 전송이 구성된 Token-2022 민트와 구성된 수신 계정이 필요합니다.

spl-token --program-2022 configure-confidential-transfer-account \
  --address <TOKEN_ACCOUNT_ADDRESS>

spl-token --program-2022 deposit-confidential-tokens \
  <MINT_ADDRESS> \
  10 \
  --address <TOKEN_ACCOUNT_ADDRESS>

spl-token --program-2022 apply-pending-balance \
  --address <TOKEN_ACCOUNT_ADDRESS>

spl-token --program-2022 withdraw-confidential-tokens \
  <MINT_ADDRESS> \
  5 \
  --address <TOKEN_ACCOUNT_ADDRESS>

spl-token --program-2022 transfer \
  <MINT_ADDRESS> \
  1 \
  <RECIPIENT_ADDRESS> \
  --confidential

configure-confidential-transfer-account와 apply-pending-balance에는 --address <TOKEN_ACCOUNT_ADDRESS> 또는 위치 인자 <MINT_ADDRESS> 중 하나만 전달하고, 둘 다 전달하지 마십시오. 위치 인자 형식은 소유자의 associated token account를 사용합니다. 입금과 출금은 항상 민트를 인자로 받으며, --address를 사용하면 해당 기본 계정을 재정의할 수 있습니다.

enable-confidential-credits, disable-confidential-credits, enable-non-confidential-credits, disable-non-confidential-credits를 사용하여 계정이 수락하는 입금을 제어합니다. 이 설정은 계정 프라이버시와 결제 호환성에 영향을 미치므로 변경하기 전에 계정을 확인하십시오.

전체 명령어 색인

다음 색인에는 spl-token-cli v5.6.1의 모든 최상위 명령이 포함되어 있습니다.

명령	설명
`accounts`	지갑이 소유한 token account를 나열하며, 선택적으로 민트별로 필터링할 수 있습니다.
`address`	선택한 지갑 주소 또는 해당 associated token 주소를 출력합니다.
`apply-pending-balance`	대기 중인 기밀 토큰을 사용 가능한 기밀 잔액으로 이동합니다.
`approve`	token account의 위임자와 지출 허용량을 승인합니다.
`authorize`	민트, 계정 또는 확장 기능 권한을 변경하거나 비활성화합니다.
`balance`	token account 잔액을 표시합니다.
`bench`	토큰 벤치마킹 명령을 실행합니다.
`burn`	계정의 토큰을 소각하고 민트 공급량을 줄입니다.
`close`	종료 가능한 token account를 닫고 해당 lamport를 회수합니다.
`close-mint`	close-mint 확장 기능이 구성된 Token-2022 민트를 닫습니다.
`configure-confidential-transfer-account`	계정이 기밀 전송을 사용하도록 구성합니다.
`create-account`	associated token account 또는 보조 token account를 생성합니다.
`create-multisig`	M-of-N Token Program 멀티시그를 생성합니다.
`create-token`	민트를 생성하며, 선택적으로 Token-2022 확장 기능을 포함할 수 있습니다.
`deposit-confidential-tokens`	비기밀 토큰을 대기 중인 기밀 잔액으로 이동합니다.
`disable-confidential-credits`	계정으로 들어오는 기밀 전송을 거부합니다.
`disable-cpi-guard`	계정의 CPI Guard를 비활성화합니다.
`disable-non-confidential-credits`	기밀 계정으로 들어오는 비기밀 전송을 거부합니다.
`disable-required-transfer-memos`	수신 전송에 메모 포함을 더 이상 요구하지 않습니다.
`display`	민트, token account 또는 멀티시그의 전체 세부 정보를 표시합니다.
`enable-confidential-credits`	구성된 계정으로 들어오는 기밀 전송을 수락합니다.
`enable-cpi-guard`	CPI를 통해 호출될 때 선택된 토큰 작업을 제한합니다.
`enable-non-confidential-credits`	기밀 계정으로 들어오는 비기밀 전송을 수락합니다.
`enable-required-transfer-memos`	수신 전송에 메모 포함을 요구합니다.
`freeze`	민트의 동결 권한을 사용하여 token account를 동결합니다.
`gc`	불필요한 token account를 닫고 가능한 경우 잔액을 통합합니다.
`help`	루트 또는 명령 도움말을 출력합니다.
`initialize-group`	민트의 Token-2022 그룹 구성을 초기화합니다.
`initialize-member`	Token-2022 민트를 그룹 구성원으로 추가합니다.
`initialize-metadata`	내장 Token-2022 메타데이터를 초기화합니다.
`mint`	민트 권한을 사용하여 새 토큰을 발행합니다.
`pause`	일시 중지 가능한 Token-2022 민트의 발행, 소각, 전송을 일시 중지합니다.
`resume`	일시 중지된 Token-2022 민트의 작업을 재개합니다.
`revoke`	token account 위임자를 제거합니다.
`set-interest-rate`	이자 발생 민트의 이율을 업데이트합니다.
`set-transfer-fee`	새 전송 수수료 매개변수를 예약합니다.
`set-transfer-hook`	민트의 transfer hook 프로그램 ID를 변경합니다.
`supply`	민트의 총 공급량을 표시합니다.
`sync-native`	래핑된 SOL 계정의 수량을 해당 lamport와 동기화합니다.
`thaw`	동결된 token account의 동결을 해제합니다.
`transfer`	토큰을 token account 또는 지갑으로 전송합니다.
`unwrap`	래핑된 SOL 계정을 닫고 모든 lamport를 회수합니다.
`unwrap-sol`	래핑된 SOL 계정에서 일부 또는 전체 SOL을 제거합니다.
`update-confidential-transfer-settings`	민트의 기밀 전송 승인 또는 감사자 설정을 업데이트합니다.
`update-default-account-state`	새 token account에 대한 민트의 기본 상태를 변경합니다.
`update-group-address`	민트의 그룹 포인터 주소를 변경합니다.
`update-group-max-size`	토큰 그룹의 최대 구성원 수를 변경합니다.
`update-member-address`	민트의 그룹 구성원 포인터 주소를 변경합니다.
`update-metadata`	내장 메타데이터 필드를 변경하거나 제거합니다.
`update-metadata-address`	민트의 메타데이터 포인터 주소를 변경합니다.
`update-ui-amount-multiplier`	새로운 스케일링 UI 수량 배수를 예약합니다.
`withdraw-confidential-tokens`	기밀 토큰을 비기밀 잔액으로 되돌립니다.
`withdraw-excess-lamports`	Token Program 계정에서 렌트 면제 잔액을 초과하는 lamport를 인출합니다.
`withdraw-withheld-tokens`	token account 또는 민트에 보류된 전송 수수료를 수거합니다.
`wrap`	SOL을 네이티브 민트 token account에 래핑합니다.

구조화된 서명 및 오프라인 서명

표시 텍스트를 파싱하는 대신 구조화된 출력을 사용하십시오:

spl-token accounts --output json
spl-token display <MINT_ADDRESS> --output json-compact

트랜잭션을 생성하는 명령은 대체로 --sign-only, --blockhash, --signer <PUBKEY=SIGNATURE>, --nonce, --nonce-authority를 지원합니다. 정확한 오프라인 입력은 명령, 민트 소수점 자릿수, 권한 구성에 따라 다르므로, 해당 명령의 --help 안내에 따라 서명되지 않은 메시지를 생성하고 서명을 수집하기 전에 모든 주소를 확인하십시오.

목차