Expand description
Unified Symbol Format Module
This module provides comprehensive parsing, formatting, and analysis functionality for unified trading pair symbols across different market types (Spot, Swap, Futures) and settlement currencies (Linear/Inverse).
§Overview
The unified symbol format follows the CCXT standard, providing a consistent way to represent trading pairs across all supported cryptocurrency exchanges. This enables seamless interoperability and simplifies cross-exchange trading operations.
§Symbol Format
| Market Type | Format | Example |
|---|---|---|
| Spot | BASE/QUOTE | BTC/USDT |
| Linear Swap | BASE/QUOTE:SETTLE (settle = quote) | BTC/USDT:USDT |
| Inverse Swap | BASE/QUOTE:SETTLE (settle = base) | BTC/USD:BTC |
| Futures | BASE/QUOTE:SETTLE-YYMMDD | BTC/USDT:USDT-241231 |
§Components
SymbolParser: Parse unified symbol strings intoParsedSymbolstructuresSymbolFormatter: FormatParsedSymbolback to unified symbol stringsSymbolError: Error types for symbol parsing and validationParsedSymbol: Structured representation of a parsed symbolExpiryDate: Futures contract expiry date in YYMMDD formatSymbolMarketType: Market type enum (Spot, Swap, Futures)ContractType: Contract settlement type (Linear, Inverse)
§Quick Start
§Parsing Symbols
use ccxt_core::symbol::{SymbolParser, ParsedSymbol};
// Parse a spot symbol
let spot = SymbolParser::parse("BTC/USDT").unwrap();
assert!(spot.is_spot());
assert_eq!(spot.base, "BTC");
assert_eq!(spot.quote, "USDT");
// Parse a perpetual swap symbol
let swap = SymbolParser::parse("BTC/USDT:USDT").unwrap();
assert!(swap.is_swap());
assert!(swap.is_linear());
// Parse a futures symbol
let futures = SymbolParser::parse("BTC/USDT:USDT-241231").unwrap();
assert!(futures.is_futures());
assert!(futures.expiry.is_some());§Using FromStr Trait
use ccxt_core::symbol::ParsedSymbol;
// Parse using the FromStr trait
let symbol: ParsedSymbol = "ETH/USDT".parse().unwrap();
assert_eq!(symbol.base, "ETH");
assert_eq!(symbol.quote, "USDT");§Creating Symbols Programmatically
use ccxt_core::symbol::{ParsedSymbol, ExpiryDate};
// Create a spot symbol
let spot = ParsedSymbol::spot("BTC".to_string(), "USDT".to_string());
assert_eq!(spot.to_string(), "BTC/USDT");
// Create a linear swap symbol
let swap = ParsedSymbol::linear_swap("ETH".to_string(), "USDT".to_string());
assert_eq!(swap.to_string(), "ETH/USDT:USDT");
// Create an inverse swap symbol
let inverse = ParsedSymbol::inverse_swap("BTC".to_string(), "USD".to_string());
assert_eq!(inverse.to_string(), "BTC/USD:BTC");
// Create a futures symbol
let expiry = ExpiryDate::new(24, 12, 31).unwrap();
let futures = ParsedSymbol::futures(
"BTC".to_string(),
"USDT".to_string(),
"USDT".to_string(),
expiry
);
assert_eq!(futures.to_string(), "BTC/USDT:USDT-241231");§Formatting Symbols
use ccxt_core::symbol::{SymbolFormatter, ParsedSymbol};
let symbol = ParsedSymbol::linear_swap("BTC".to_string(), "USDT".to_string());
// Using SymbolFormatter
let formatted = SymbolFormatter::format(&symbol);
assert_eq!(formatted, "BTC/USDT:USDT");
// Using Display trait (equivalent)
assert_eq!(symbol.to_string(), "BTC/USDT:USDT");
// Using helper methods
assert_eq!(SymbolFormatter::format_spot("BTC", "USDT"), "BTC/USDT");
assert_eq!(SymbolFormatter::format_swap("BTC", "USDT", "USDT"), "BTC/USDT:USDT");§Analyzing Symbols
use ccxt_core::symbol::{SymbolParser, SymbolMarketType, ContractType};
let symbol = SymbolParser::parse("BTC/USDT:USDT").unwrap();
// Check market type
assert_eq!(symbol.market_type(), SymbolMarketType::Swap);
assert!(symbol.is_swap());
assert!(symbol.is_derivative());
// Check contract type
assert_eq!(symbol.contract_type(), Some(ContractType::Linear));
assert!(symbol.is_linear());§Error Handling
use ccxt_core::symbol::{SymbolParser, SymbolError};
// Invalid format
let result = SymbolParser::parse("BTCUSDT");
assert!(result.is_err());
// Invalid date in futures symbol
let result = SymbolParser::parse("BTC/USDT:USDT-241301"); // month 13
assert!(result.is_err());
// Validate without parsing
assert!(SymbolParser::validate("BTC/USDT").is_ok());
assert!(SymbolParser::validate("invalid").is_err());§Round-Trip Consistency
The symbol module guarantees round-trip consistency: parsing a formatted symbol and formatting it again produces the same result.
use ccxt_core::symbol::{SymbolParser, SymbolFormatter, ParsedSymbol};
let original = "BTC/USDT:USDT-241231";
let parsed = SymbolParser::parse(original).unwrap();
let formatted = SymbolFormatter::format(&parsed);
let reparsed = SymbolParser::parse(&formatted).unwrap();
assert_eq!(parsed, reparsed);
assert_eq!(formatted, original);Re-exports§
pub use error::SymbolError;pub use formatter::SymbolFormatter;pub use parser::SymbolParser;pub use crate::types::symbol::ContractType;pub use crate::types::symbol::ExpiryDate;pub use crate::types::symbol::ParsedSymbol;pub use crate::types::symbol::SymbolMarketType;