> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trysinker.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Submit a Solana transaction through Sinker and watch it finalize on-chain in under 5 minutes.

## What is Sinker?

Sinker is a two-layer transaction reliability stack for Solana. It combines:

* A **Rust sidecar** that tracks every stage of the transaction lifecycle — from bundle submission to on-chain finalization — using a live Yellowstone gRPC stream.
* An **AI agent** that makes tip selection, submission timing, and retry decisions grounded in real-time oracle data and historical bundle outcomes.

The TypeScript SDK gives you a clean async interface over the sidecar without dealing with raw HTTP or SSE.

```
Your App → sinker-sdk → Rust Sidecar → Jito Block Engine → Solana
                              ↑
                         AI Agent (decides when + how much to tip)
```

***

## Start the stack

<Tabs>
  <Tab title="Full stack (recommended)">
    ```bash theme={null}
    sinker up
    ```

    Starts both the sidecar and the AI agent together. Both log streams appear in the same terminal — agent lines are prefixed with `[ AGENT ]`.
  </Tab>

  <Tab title="Sidecar only">
    ```bash theme={null}
    sinker start
    ```

    Starts only the Rust sidecar. The AI agent must be started separately with `sinker agent`.
  </Tab>

  <Tab title="Agent only">
    ```bash theme={null}
    sinker agent
    ```

    Starts only the TypeScript AI agent. Requires the sidecar to already be running.
  </Tab>
</Tabs>

***

## Prerequisites

<CardGroup cols={2}>
  <Card title="Rust sidecar running" icon="server">
    The sidecar must be running at `localhost:7777` before the SDK can connect.
    See the [README](https://github.com/ubadineke/sinker) for setup.
  </Card>

  <Card title="Model API key" icon="key">
    Sinker's AI agent requires a provider key. Set `ANTHROPIC_API_KEY`,
    `OPENAI_API_KEY`, `GROQ_API_KEY`, or `XAI_API_KEY` in your environment.
  </Card>

  <Card title="Pre-signed transaction" icon="pen">
    The SDK never touches your keypair. Sign the transaction yourself and pass
    the base64-encoded wire bytes to `sinker.enqueue()`.
  </Card>
</CardGroup>

***

## Install

```bash theme={null}
npm install sinker-sdk
```

***

## Submit your first transaction

```ts theme={null}
import { Sinker } from 'sinker-sdk';
import { Connection, Keypair, SystemProgram, Transaction, sendAndConfirmTransaction } from '@solana/web3.js';
import bs58 from 'bs58';

// 1. Connect to the running sidecar with your model provider
const sinker = new Sinker({
  model: {
    provider: 'anthropic',
    apiKey: process.env.ANTHROPIC_API_KEY!,
  },
  // sidecarUrl defaults to http://localhost:7777
});

// 2. Sign your transaction externally — Sinker never sees your keypair
const tx = buildAndSignMyTransaction(); // your signing code
const rawTxBase64 = Buffer.from(tx.serialize()).toString('base64');

// 3. Enqueue it
const handle = await sinker.enqueue(rawTxBase64);
console.log('Enqueued:', handle.txId);

// 4. Wait for finalization
const result = await handle.waitFor('finalized');
console.log('Finalized sigs:', result.tx_signatures);

// 5. Clean up
sinker.destroy();
```

<Note>
  The AI agent fires automatically on the `tx_enqueued` SSE event. You don't need to call `submit()` manually — the agent selects a tip and submits the bundle.
</Note>

***

## What happens under the hood

<Steps>
  <Step title="Enqueue">
    `sinker.enqueue()` POSTs your transaction bytes to `/tx/enqueue`. The sidecar
    assigns a `tx_id`, fires a `tx_enqueued` SSE event, and returns immediately.
  </Step>

  <Step title="Agent decides">
    The AI agent receives the SSE event, checks the live tip oracle, reviews
    failure history, and selects a tip percentile. It calls `POST /internal/submit`
    with `tx_ids` and `tip_lamports`.
  </Step>

  <Step title="Jito bundle">
    The sidecar builds a Jito bundle (your tx + tip tx), submits it to the block
    engine, and starts a background status tracker.
  </Step>

  <Step title="SSE confirmation">
    The Yellowstone gRPC stream fires as each commitment stage is reached.
    The sidecar broadcasts `tx_status_changed` SSE events. `handle.waitFor()`
    resolves when your target state arrives.
  </Step>
</Steps>