--- name: onboarding description: Onboard new agents and users to TTC Box trading platform. Handles registration, API key setup, wallet connection, and initial configuration. Use when a new agent or user needs to get started with the platform. license: Proprietary compatibility: Designed for Claude Code (or similar products) metadata: author: ttcbox version: "1.0" category: "onboarding" emoji: "🚀" --- ## Skill Files | File | URL | | ------------------------ | ----------------------------------------------- | | **SKILL.md** (this file) | `https://tetrac.xyz/skills/onboarding/SKILL.md` | ## Overview This skill guides new agents and users through the TTC Box onboarding process: 1. **Registration** - Create an account (email or wallet) 2. **API Key Setup** - Get and store credentials 3. **First API Call** - Verify connectivity 4. **Exchange Connection** - Connect trading exchanges --- ## Step 1: Register Every agent needs to register and get an API key. ### How It Works Behind the Scenes Regardless of registration method (email or wallet), the **Solana public key is always the universal user identifier**. The server stores and looks up all user data by `pubKey:{solanaPublicKey}`, and auth tokens are keyed the same way. This means: - **Email users**: The client generates all wallets (Solana, Orderly, EVM, EVM Signing) before calling register. The server uses `clientGeneratedWallets.solana.publicKey` as the user's identity key. A synthetic email (`{pubKey}@ttc.box`) is not generated — the real email is stored, but it is not the lookup key. - **Wallet users**: The user's existing Solana `pubKey` is sent directly and used as the identity key. The client still generates the remaining wallets (Orderly, EVM, EVM Signing) and sends them along. In both cases, the complete registration flow is: 1. **Client generates wallets** — Solana, Orderly, EVM, and EVM Signing keypairs 2. **Client encrypts all private keys** — using a key derived from the user's passkey + email (server never sees plaintext keys) 3. **Client hashes the passkey** — SHA-256 hash sent to server; plaintext passkey stays client-side 4. **Server resolves the identity key** — for email users: `clientGeneratedWallets.solana.publicKey`; for wallet users: the `pubKey` field 5. **Server stores user data** — keyed by `pubKey:{identityKey}`, with all encrypted blobs stored as-is 6. **Server generates an auth token** — a random 64-char hex string, stored with a 24-hour TTL keyed by the same public key ### Option A: Email Registration The client must generate all four wallet keypairs, encrypt the private keys, and include them in the request. The `pubKey` field can be `null` because the server derives the identity key from `clientGeneratedWallets.solana.publicKey`: ```bash curl -X POST https://tetrac.xyz/api/auth/register \ -H "Content-Type: application/json" \ -d '{ "email": "agent@example.com", "pubKey": null, "hashedPasskey": "SHA256_HASH_OF_PASSKEY", "clientGeneratedWallets": { "solana": { "publicKey": "YOUR_SOLANA_PUBLIC_KEY", "encryptedPrivateKey": "CLIENT_ENCRYPTED_BLOB" }, "orderly": { "publicKey": "YOUR_ORDERLY_PUBLIC_KEY", "encryptedPrivateKey": "CLIENT_ENCRYPTED_BLOB" }, "evm": { "address": "0xYOUR_EVM_ADDRESS", "encryptedPrivateKey": "CLIENT_ENCRYPTED_BLOB" }, "evmSigning": { "address": "0xYOUR_EVM_SIGNING_ADDRESS", "encryptedPrivateKey": "CLIENT_ENCRYPTED_BLOB" } } }' ``` > **Identity key used:** `clientGeneratedWallets.solana.publicKey` (since `pubKey` is null) ### Option B: Wallet Registration (Solana) The user's existing Solana wallet public key is the identity key. The client still generates the remaining wallets (Orderly, EVM, EVM Signing). A synthetic email is generated server-side (`{pubKey}@ttc.box`): ```bash curl -X POST https://tetrac.xyz/api/auth/register \ -H "Content-Type: application/json" \ -d '{ "email": null, "pubKey": "J4b1guxqqwYvKE2ZamGyLNbCcgQrcHbpYS6WpQz3qYMa", "hashedPasskey": "SHA256_HASH_OF_PASSKEY", "clientGeneratedWallets": { "solana": { "publicKey": "...", "encryptedPrivateKey": "..." }, "orderly": { "publicKey": "...", "encryptedPrivateKey": "..." }, "evm": { "address": "...", "encryptedPrivateKey": "..." }, "evmSigning": { "address": "...", "encryptedPrivateKey": "..." } } }' ``` > **Identity key used:** the `pubKey` field directly > **Note:** All private keys must be encrypted client-side before sending. The server stores encrypted blobs as-is and cannot decrypt them. The Orderly wallet is required — registration will fail without `orderly.publicKey` and `orderly.encryptedPrivateKey`. ### Response (New User) ```json { "success": true, "message": "User registered successfully", "authToken": "a1b2c3d4e5f6..." } ``` ### Response (Existing User) ```json { "success": true, "message": "User already exists - returning existing data", "isNewUser": false, "authToken": "a1b2c3d4e5f6...", "user": { ... } } ``` **Save your `authToken` immediately — it expires after 24 hours.** --- ## Step 2: Store Credentials Use the `authToken` from registration as the `ttc-auth-token` header, and the **identity key** (Solana public key) as `ttc-public-key`. This is the same key the server used to store your user data — it must match exactly: | Header | Value | | ---------------- | ----------------------------------------------------------------------------------- | | `ttc-auth-token` | The `authToken` returned from registration (expires after 24h) | | `ttc-public-key` | Your Solana public key — the identity key resolved during registration (see Step 1) | > **Reminder:** For both email and wallet users, this is always a Solana public key. Email users: use `clientGeneratedWallets.solana.publicKey`. Wallet users: use the `pubKey` you registered with. The server validates auth tokens against this key. --- ## Step 3: Verify Connectivity Test your setup with a health check: ```bash curl https://tetrac.xyz/api/health \ -H "ttc-auth-token: YOUR_AUTH_TOKEN" \ -H "ttc-public-key: YOUR_PUBLIC_KEY" ``` Expected response: ```json { "success": true, "status": "ok" } ``` --- ## Step 4: Get Market Data Try fetching tickers to verify API access: ```bash curl https://tetrac.xyz/api/v1/markets/hybrid-tickers \ -H "ttc-auth-token: YOUR_AUTH_TOKEN" \ -H "ttc-public-key: YOUR_PUBLIC_KEY" ``` --- ## Step 5: Connect Exchange (Optional) To trade, connect your exchange API credentials: ```bash curl -X POST https://tetrac.xyz/api/v1/exchanges \ -H "ttc-auth-token: YOUR_AUTH_TOKEN" \ -H "ttc-public-key: YOUR_PUBLIC_KEY" \ -H "Content-Type: application/json" \ -d '{ "exchangeName": "binance", "method": "getBalance", "params": {}, "credentials": { "apiKey": "YOUR_EXCHANGE_API_KEY", "apiSecret": "YOUR_EXCHANGE_API_SECRET" } }' ``` ### Orderly Network (Agentic / CLI Users) Orderly derives your account ID from your **main wallet address** (Solana public key) + broker ID. For web3-registered users, the `ttc-public-key` IS the main wallet, so no extra step is needed. But for **email-registered users** (the agentic path), the `ttc-public-key` is a random DB identifier with no Orderly account. To trade on Orderly as an email-registered user, pass your **real Orderly trading wallet address** in `credentials.walletAddress`: ```bash curl -X POST https://tetrac.xyz/api/v1/exchanges \ -H "ttc-auth-token: YOUR_AUTH_TOKEN" \ -H "ttc-public-key: YOUR_PUBLIC_KEY" \ -H "Content-Type: application/json" \ -d '{ "exchangeName": "orderly", "method": "getPositions", "params": {}, "credentials": { "apiKey": "YOUR_ORDERLY_ED25519_PUBLIC_KEY", "apiSecret": "YOUR_ORDERLY_ED25519_PRIVATE_KEY", "passphrase": "ttc", "walletAddress": "YOUR_SOLANA_MAIN_WALLET_ADDRESS" } }' ``` | Credential | Description | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiKey` | Ed25519 trading wallet **public key** (the `orderly-key`, not your main wallet) | | `apiSecret` | Ed25519 trading wallet **private key** (hex string, signs every request) | | `passphrase` | Broker ID (default: `ttc`) | | `walletAddress` | Your **main Solana wallet address** — the funded wallet linked to your Orderly account. Required for email-registered users; omit for web3 users (server uses `ttc-public-key` automatically) | > **How it works:** The server uses `walletAddress` (if provided) or falls back to `ttc-public-key` to derive the Orderly `accountId` via `keccak256(walletAddress, brokerId)`. Email users must provide `walletAddress` because their `ttc-public-key` is not an Orderly-linked wallet. --- ## Common Issues ### Invalid API Key - Verify you're using the correct `ttc-auth-token` and `ttc-public-key` headers - Check for typos in credentials file ### Rate Limited (429) - Check `Retry-After` header - Reduce request frequency - Higher karma users get increased limits ### Exchange Connection Failed - Verify exchange API keys have correct permissions - Check IP whitelist settings on exchange --- ## Next Steps After onboarding: 1. Explore [market data endpoints](/skills/market-data/SKILL.md) 2. Learn [trading operations](/skills/trading/SKILL.md) 3. Set up [x402 agent payments](/skills/x402-agent-payments/SKILL.md) --- **Full API Documentation:** https://tetrac.xyz/docs/api