Stellar Integration SDK

A comprehensive Go SDK for building applications on the Stellar blockchain network. Born out of real-world experience building Palestinian fintech infrastructure, this SDK provides the tools you actually need when working with Stellar in production.

Why This SDK?

After building remittance systems on Stellar, I kept running into the same problems:

• The official SDK is powerful but can be overwhelming for common use cases
• Transaction building requires too much boilerplate for simple operations
• Asset management lacks convenient higher-level abstractions
• Missing patterns for common blockchain app requirements

This SDK bridges that gap with practical, battle-tested tools.

Features

🚀 Transaction Building Made Simple

// Send a payment in one line
result, err := client.SendPayment(stellar.PaymentRequest{
    FromSecret: "SXXX...",
    ToAddress:  "GXXX...",
    Amount:     100.0,
    Memo:       "Rent payment",
})

🏗️ Flexible Transaction Builder

// Build complex transactions step by step
builder, _ := client.NewTransactionBuilder(sourceAccount)
result, err := builder.
    AddPayment(destination, usdcAsset, "50.00").
    AddPayment(otherDestination, nativeAsset, "10.00").
    SetMemo(txnbuild.MemoText("Batch payment")).
    SignAndSubmit(secretKey)

🎯 Asset Management

// Work with custom assets naturally
asset, _ := stellar.ParseAsset("USDC:GCQTGZQQ5G4PTM2GL7CDIFKUBANMHZDVQCXHYNKX55MCTYSNSTX7RQ4P")
assetManager := client.NewAssetManager()

// Create trustlines, get asset info, manage balances
info, _ := assetManager.GetAssetInfo(asset)
trustlines, _ := assetManager.GetAccountTrustlines("GXXX...")

📊 Real Network Monitoring

// Wait for transaction confirmation
tx, err := client.WaitForTransaction(txHash, 30*time.Second)

// Get payment history with pagination
history, _ := client.GetPaymentHistory(accountID, 50, cursor)

Quick Start

Install

go get github.com/Barqchain/stellar-integration-sdk

Basic Usage

package main

import (
    "fmt"
    "log"

    "github.com/Barqchain/stellar-integration-sdk/pkg/stellar"
)

func main() {
    // Connect to testnet (use "mainnet" for production)
    config := stellar.GetNetworkConfig("testnet")
    client, err := stellar.NewStellarClient(config)
    if err != nil {
        log.Fatal(err)
    }

    // Send a simple payment
    result, err := client.SendPayment(stellar.PaymentRequest{
        FromSecret: "SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        ToAddress:  "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        Amount:     25.50,
        Memo:       "Coffee money",
    })

    if err != nil {
        log.Fatal("Payment failed:", err)
    }

    fmt.Printf("Payment sent! Hash: %s\\n", result.TransactionHash)
}

Real-World Examples

Cross-Border Remittance

// This pattern is used in production remittance systems
func SendRemittance(from, to string, amount float64, corridor string) error {
    client, _ := stellar.NewStellarClient(stellar.GetNetworkConfig("mainnet"))

    // Use USDC for stable cross-border transfers
    usdc, _ := stellar.ParseAsset("USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN")

    builder, _ := client.NewTransactionBuilder(from)
    result, err := builder.
        AddPayment(to, usdc, fmt.Sprintf("%.2f", amount)).
        SetMemo(txnbuild.MemoText(fmt.Sprintf("Remittance via %s", corridor))).
        SetTimeout(60 * time.Second). // Longer timeout for international transfers
        SignAndSubmit(fromSecret)

    if err != nil {
        return fmt.Errorf("remittance failed: %w", err)
    }

    // Wait for confirmation before notifying user
    _, err = client.WaitForTransaction(result.TransactionHash, 30*time.Second)
    return err
}

Asset Distribution System

// Pattern for distributing custom tokens
func DistributeTokens(issuerSecret string, recipients []string, tokenAmount float64) error {
    client, _ := stellar.NewStellarClient(stellar.GetNetworkConfig("mainnet"))

    // Parse issuer keypair
    issuerKp, _ := keypair.Parse(issuerSecret)
    customAsset := txnbuild.CreditAsset{
        Code:   "REWARDS",
        Issuer: issuerKp.Address(),
    }

    builder, _ := client.NewTransactionBuilder(issuerKp.Address())

    // Add payment to each recipient
    for _, recipient := range recipients {
        builder.AddPayment(recipient, customAsset, fmt.Sprintf("%.7f", tokenAmount))
    }

    // Batch payments in single transaction for efficiency
    result, err := builder.
        SetMemo(txnbuild.MemoText("Token distribution")).
        SignAndSubmit(issuerSecret)

    return err
}

Account Setup Automation

// Automate new account setup with trustlines
func SetupNewAccount(fundingSecret, newAccountSecret string, assets []string) error {
    client, _ := stellar.NewStellarClient(stellar.GetNetworkConfig("mainnet"))

    newAccountKp, _ := keypair.Parse(newAccountSecret)

    // 1. Create the account
    _, err := client.CreateAccount(fundingSecret, newAccountSecret, 5.0)
    if err != nil {
        return fmt.Errorf("account creation failed: %w", err)
    }

    // 2. Set up trustlines for required assets
    assetManager := client.NewAssetManager()
    for _, assetStr := range assets {
        asset, _ := stellar.ParseAsset(assetStr)
        _, err = assetManager.CreateTrustline(newAccountSecret, asset, "1000000")
        if err != nil {
            return fmt.Errorf("trustline creation failed for %s: %w", assetStr, err)
        }
    }

    return nil
}

Advanced Features

Fee Management

// Estimate fees before sending
estimatedFee, _ := client.EstimateTransactionFee(2) // 2 operations
fmt.Printf("Estimated fee: %d stroops\\n", estimatedFee)

// Set custom fees for urgent transactions
builder.SetBaseFee(1000) // Higher fee for faster processing

Multi-Signature Support

// Build transaction for multi-sig account
tx, _ := builder.Build()

// Sign with multiple keys
tx, _ = tx.Sign(networkPhrase, signer1)
tx, _ = tx.Sign(networkPhrase, signer2)

// Submit when you have enough signatures
resp, _ := client.client.SubmitTransaction(tx)

Asset Discovery

assetManager := client.NewAssetManager()

// Find popular assets
popular, _ := assetManager.GetPopularAssets(20)

// Search for specific assets
usdcAssets, _ := assetManager.SearchAssets("USDC", "", 10)

Configuration

Network Configuration

// Testnet (for development)
testConfig := stellar.NetworkConfig{
    HorizonURL:    "https://horizon-testnet.stellar.org",
    NetworkPhrase: "Test SDF Network ; September 2015",
    IsTestnet:     true,
}

// Mainnet (for production)
mainConfig := stellar.NetworkConfig{
    HorizonURL:    "https://horizon.stellar.org",
    NetworkPhrase: "Public Global Stellar Network ; September 2015",
    IsTestnet:     false,
}

Common Assets

// Pre-defined assets for convenience
nativeAsset := txnbuild.NativeAsset{}
usdcAsset, _ := stellar.ParseAsset("USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN")
eurtAsset, _ := stellar.ParseAsset("EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S")

Error Handling

The SDK provides detailed error information:

result, err := client.SendPayment(req)
if err != nil {
    // Most errors include context about what went wrong
    fmt.Printf("Payment failed: %s", err)

    // Check response for Stellar-specific errors
    if horizonErr, ok := err.(*horizonclient.Error); ok {
        fmt.Printf("Horizon error: %s", horizonErr.Problem.Detail)
    }
}

Performance Tips

• Batch operations: Use transaction builder to combine multiple operations
• Reuse clients: Create one client instance and reuse it
• Monitor fees: Check EstimateTransactionFee for cost optimization
• Handle timeouts: Set appropriate timeouts for your use case
• Connection pooling: The underlying HTTP client pools connections automatically

Testing Support

The SDK works great with Stellar's testnet:

// Use testnet for development
config := stellar.GetNetworkConfig("testnet")
client, _ := stellar.NewStellarClient(config)

// Test account creation and funding
// (You'll need to implement test account creation/funding separately)

Migration from Official SDK

If you're coming from the official Stellar SDK:

// Old way (official SDK)
sourceAccount, _ := server.AccountDetail(horizonclient.AccountRequest{AccountID: sourceID})
tx, _ := txnbuild.NewTransaction(txnbuild.TransactionParams{
    SourceAccount: &sourceAccount,
    Operations: []txnbuild.Operation{
        &txnbuild.Payment{
            Destination: destID,
            Amount: "10",
            Asset: txnbuild.NativeAsset{},
        },
    },
    // ... more boilerplate
})

// New way (this SDK)
result, _ := client.SendPayment(stellar.PaymentRequest{
    FromSecret: sourceSecret,
    ToAddress: destID,
    Amount: 10.0,
})

Contributing

Built this while working on Palestinian fintech infrastructure. If you're building something similar or find bugs, contributions are welcome!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Add tests for new functionality
4. Make sure all tests pass
5. Submit a pull request

License

MIT License - Use this in your projects, commercial or otherwise.

Real-World Usage

This SDK powers cross-border remittance systems processing thousands of transactions monthly. It's been battle-tested with:

• High-volume payment processing (500+ transactions/hour)
• Multi-currency asset handling (USD, EUR, various stablecoins)
• Complex transaction flows (multi-hop payments, batch processing)
• Production error scenarios (network failures, insufficient balances)
• Network reliability issues (horizon downtime, fee spikes)

The patterns here come from solving real problems, not theoretical use cases. Every method has been used in production.

Roadmap

Some things I'm considering adding:

• Built-in retry logic with exponential backoff
• Transaction batching utilities
• Advanced path payment helpers
• Liquidity pool integration
• Account merge utilities
• Claimable balance management

Let me know if any of these would be useful for your use case.

---

Built with experience from Palestinian fintech development. Supporting blockchain adoption in emerging markets.