capital-rust-sdk

Unofficial Rust SDK for Capital.com CFD trading API.

Features

• Session management with automatic background token refresh (8-min interval)
• Arc-safe client — share across tokio tasks freely
• Builder pattern with optional HTTP/SOCKS5 proxy support
• Per-module custom errors via thiserror
• Structured logging via log + env_logger

Implemented API Endpoints

Module	Method	Endpoint	Description
Session	login()	POST /api/v1/session	Authenticate and obtain session tokens
Session	logout()	DELETE /api/v1/session	End session and stop background refresh
Session	get_session()	GET /api/v1/session	Get current session details
Market	get_market(epic)	GET /api/v1/markets/{epic}	Get market details, price, dealing rules
Market	search_markets(term)	GET /api/v1/markets?searchTerm=	Search for markets by keyword
Trade	open_position(req)	POST /api/v1/positions	Open a market order (supports stop/profit options)
Trade	confirm_deal(ref)	GET /api/v1/confirms/{ref}	Get deal confirmation and actual deal ID
Trade	get_position(id)	GET /api/v1/positions/{dealId}	Get a specific position's details

Project Structure

src/
├── lib.rs
├── error.rs                    # CapitalError, CapitalResult
├── client/
│   ├── mod.rs                  # CapitalClient, Arc<ClientInner>, auth_request
│   ├── builder.rs              # CapitalClientBuilder (live/demo, proxy)
│   └── session_manager.rs      # Background session refresh task
├── session/
│   ├── api/
│   │   ├── login.rs            # POST /session
│   │   ├── logout.rs           # DELETE /session
│   │   └── get_session.rs      # GET /session
│   └── models/
│       ├── login.rs            # LoginRequest, LoginResponse
│       ├── session_details.rs  # SessionDetails
│       └── error.rs            # SessionError
├── market/
│   ├── api/
│   │   ├── get_market.rs       # GET /markets/{epic}
│   │   └── search_markets.rs   # GET /markets?searchTerm=
│   └── models/
│       ├── market_details.rs   # MarketDetails, Instrument, Snapshot
│       ├── search_result.rs    # MarketSearchResult
│       └── error.rs            # MarketError
└── trade/
    ├── api/
    │   ├── open_position.rs    # POST /positions
    │   ├── confirm.rs          # GET /confirms/{ref}
    │   └── get_position.rs     # GET /positions/{dealId}
    └── models/
        ├── open_position.rs    # Direction, OpenPositionRequest/Response
        ├── confirm.rs          # DealConfirmation, AffectedDeal
        ├── get_position.rs     # PositionResponse, PositionData, PositionMarket
        └── error.rs            # TradeError

Quick Start

use capital_rust_sdk::CapitalClient;
use capital_rust_sdk::trade::models::{Direction, OpenPositionRequest};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = CapitalClient::builder()
        .identifier("your_email")
        .password("your_password")
        .api_key("your_api_key")
        .demo()
        .build()?;

    client.login().await?;

    // Get market price
    let market = client.get_market("BTCUSD").await?;
    println!("BTC bid: {}, offer: {}", market.snapshot.bid, market.snapshot.offer);

    // Open a short position with $5 max loss
    let resp = client.open_position(&OpenPositionRequest {
        epic: "BTCUSD".into(),
        direction: Direction::Sell,
        size: 0.001,
        stop_amount: Some(5.0),
        guaranteed_stop: None,
        trailing_stop: None,
        stop_level: None,
        stop_distance: None,
        profit_level: None,
        profit_distance: None,
        profit_amount: None,
    }).await?;

    // Confirm and get position ID
    let confirm = client.confirm_deal(&resp.deal_reference).await?;
    let deal_id = confirm.affected_deals.unwrap()[0].deal_id.clone();
    let position = client.get_position(&deal_id).await?;

    client.logout().await?;
    Ok(())
}

Configuration

Copy .env.example to .env and fill in your credentials:

CAPITAL_IDENTIFIER=your_email
CAPITAL_PASSWORD=your_password
CAPITAL_API_KEY=your_api_key
CAPITAL_ENV=demo
CAPITAL_PROXY=socks5://127.0.0.1:1080  # optional

Examples

cargo run --example session        # Login / session info / logout
cargo run --example market_price   # Get BTC and search gold markets
cargo run --example trade          # Open short BTC position

License

MIT

---

Generated by Claude Opus 4.6