Skip to content
Darkfibre Documentation

Core Concepts

This section explains how Darkfibre works under the hood and how to interact with it. It’s designed for developers who want to:

  • Understand what sdk.buy() and other SDK methods do internally
  • Build custom integrations without using the SDK
  • Use a different programming language (Python examples included)
  • Debug issues by understanding the complete flow

If you’re using the TypeScript SDK, it handles all of this automatically. You can skip this section and jump straight to the SDK documentation.

The Architecture

Section titled “The Architecture”

Darkfibre is designed to keep your trading non-custodial: we build optimized transactions for you and you sign them locally. Your private key never leaves your device.

Here’s the complete flow when you execute a trade:

sequenceDiagram
    participant App
    participant DarkfibreAPI as Darkfibre API
    participant Solana
    
    App->>DarkfibreAPI: 1. Build (POST /tx/buy)
    DarkfibreAPI-->>App: unsigned tx + submissionToken
    App->>App: 2. Sign locally (private key never leaves)
    App->>DarkfibreAPI: 3. Submit (POST /tx/submit)
    DarkfibreAPI->>Solana: Broadcast to network
    Solana-->>DarkfibreAPI: Confirmation
    DarkfibreAPI-->>App: 4. Result (signature, amounts)

Key Concepts

Section titled “Key Concepts”

Non-custodial

Section titled “Non-custodial”

Your private key never leaves your device. The API builds transactions, but you sign them locally before submission. This gives you the speed and convenience of a managed service with complete self-custody.

Wire Transactions

Section titled “Wire Transactions”

Every “build” endpoint (like POST /v1/tx/buy) returns an unsignedTransaction in base64-encoded wire format. This is a serialized Solana transaction ready to be decoded, signed and re-encoded.

Submission Tokens

Section titled “Submission Tokens”

The submissionToken links your built transaction on the server. When you submit the signed transaction, this token tells the server which unsigned transaction you’re submitting. The server validates that the message bytes haven’t been tampered with.

Expiry Window

Section titled “Expiry Window”

Transactions have a short validity window (expiresAt, currently ~30s). This is a Solana blockchain constraint (blockhash expiry). If you miss the window, you need to rebuild the transaction with a fresh blockhash.

HTTP Format (REST)

Section titled “HTTP Format (REST)”

All API endpoints follow this format:

  • Method + path (example: POST /v1/tx/buy)
  • Headers:
    • Authorization: Bearer api_...
    • Content-Type: application/json (for JSON bodies)
  • JSON body (request)
  • JSON response:
    • success: true and a data object
    • on errors: success: false with an error object (see Errors)

Prerequisites for Manual Implementation

Section titled “Prerequisites for Manual Implementation”

If you’re implementing this flow manually (without the SDK), you’ll need:

  • wallet keypair you can sign with
  • Solana library @solana/kit, solders…
  • HTTP client (REST) for API calls

The Four Steps

Section titled “The Four Steps”
  1. Register & authenticate - Get an API key and understand how authentication works
  2. Build a transaction - Request an unsigned transaction from the API
  3. Sign the transaction - Sign locally with your private key
  4. Submit the transaction - Send the signed transaction for broadcasting