aspens 0.5.0

Aspens crosschain trading SDK
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

# Aspens SDK Examples

## Quickstart

The core trading workflow in five steps: **connect, check balances, deposit, trade, withdraw**.

### Using the CLI

```bash
# 1. Connect & check status
aspens-cli status

# 2. View balances
aspens-cli balance

# 3. Deposit tokens (network, token symbol, amount in smallest unit)
aspens-cli deposit anvil-1 USDC 1000000

# 4. Trade
aspens-cli buy-limit <MARKET_ID> 1.5 100.50               # limit buy: quantity, price
aspens-cli buy-limit <MARKET_ID> 1.5 100.50 --post-only   # maker-only: rejected if it would cross
aspens-cli sell-market <MARKET_ID> 0.5                    # market sell: quantity

# 5. Withdraw tokens back to your wallet
aspens-cli withdraw anvil-1 USDC 500000
```

### Using the Rust SDK

See [`quickstart.rs`](quickstart.rs) for a complete example showing how to use
the `aspens` library crate directly.

### Using the REPL

```bash
aspens-repl
aspens> config
aspens> balance
aspens> deposit anvil-1 USDC 1000000
aspens> buy-limit <MARKET_ID> 1.5 100.50
aspens> buy-limit <MARKET_ID> 1.5 100.50 --post-only
aspens> withdraw anvil-1 USDC 500000
aspens> quit
```

## Setup

1. Copy `.env.sample` to `.env` and fill in:
   ```
   ASPENS_MARKET_STACK_URL=http://localhost:50051
   TRADER_PRIVKEY=<64-char-hex-private-key>
   ```

2. Verify connectivity:
   ```bash
   aspens-cli status
   aspens-cli config
   ```

## Other Examples

- [`quickstart.rs`](quickstart.rs) — Full SDK workflow (connect, deposit, trade, withdraw)
- [`transaction_hash_example.rs`](transaction_hash_example.rs) — Working with transaction hashes from order responses

## Key Concepts

- **Deposit/withdraw amounts** are in the token's smallest unit (e.g., `1000000` = 1 USDC with 6 decimals)
- **Order quantities and prices** are human-readable strings (e.g., `"1.5"`, `"100.50"`) — the SDK converts to pair decimals automatically
- **Market IDs** follow the format: `chain_network::token_address::chain_network::token_address`
- **`--post-only`** on `buy-limit`/`sell-limit` rejects the order if it would cross at submission (no on-chain lock, no gas spent) — use it to guarantee maker-side execution
- Run `aspens-cli config` to see available chains, tokens, and markets