Xaman Go SDK

A Go client library for the Xaman (formerly XUMM) API, enabling easy integration with the XRP Ledger through Xaman's platform.

Features

• 🚀 Simple and intuitive API
• 📱 Complete Xaman API coverage
• 🔐 Built-in authentication handling
• 📦 Payload creation and management
• 🎣 Webhook support
• ⚡ Lightweight with minimal dependencies
• 🧪 Comprehensive test coverage
• 📖 Rich examples and documentation

Installation

go get github.com/toradle/xaman-go

Quick Start

package main

import (
    "fmt"
    "log"

    "github.com/toradle/xaman-go"
)

func main() {
    // Initialize client with your API credentials
    client := xaman.New("your-api-key", "your-api-secret")

    // Create a payment payload
    payload := &xaman.PayloadRequest{
        TransactionType: "Payment",
        Destination:     "rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY",
        Amount:          "1000000", // 1 XRP in drops
        Memo: &xaman.Memo{
            MemoData: "Hello from Go!",
        },
    }

    // Submit the payload
    response, err := client.CreatePayload(payload)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("✅ Payload created successfully!\n")
    fmt.Printf("UUID: %s\n", response.UUID)
    fmt.Printf("Deep Link: %s\n", response.Next.Always)
    fmt.Printf("QR Code: %s\n", response.Refs.QRPng)
}

Authentication

API Credentials

Get your API credentials from the Xaman Developer Console:

client := xaman.New("your-api-key", "your-api-secret")

Options

client := xaman.New("api-key", "api-secret",
    xaman.WithTimeout(30*time.Second),
    xaman.WithBaseURL("https://xaman.app/api/v1"),
    xaman.WithUserAgent("MyApp/1.0"),
)

Usage Examples

Creating Payment Payloads

// Simple XRP payment
payload := &xaman.PayloadRequest{
    TransactionType: "Payment",
    Destination:     "rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY",
    Amount:          "1000000", // 1 XRP in drops
}

response, err := client.CreatePayload(payload)
if err != nil {
    log.Fatal(err)
}

Token Payments

// IOU/Token payment
payload := &xaman.PayloadRequest{
    TransactionType: "Payment",
    Destination:     "rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY",
    Amount: &xaman.Amount{
        Currency: "USD",
        Value:    "100",
        Issuer:   "rGWrZyQqhTp9Xu7G5Pkayo7bXjH4k4QYpf",
    },
}

Trust Line Creation

payload := &xaman.PayloadRequest{
    TransactionType: "TrustSet",
    LimitAmount: &xaman.Amount{
        Currency: "USD",
        Value:    "1000",
        Issuer:   "rGWrZyQqhTp9Xu7G5Pkayo7bXjH4k4QYpf",
    },
}

Getting Payload Status

// Get payload by UUID
payload, err := client.GetPayload("your-payload-uuid")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Status: %s\n", payload.Meta.Resolved)
if payload.Response.Dispatched {
    fmt.Printf("Transaction Hash: %s\n", payload.Response.TxID)
}

Canceling Payloads

err := client.CancelPayload("your-payload-uuid")
if err != nil {
    log.Fatal(err)
}

Webhook Handling

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    // Verify webhook signature
    if !xaman.VerifyWebhook(r, "your-webhook-secret") {
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }

    // Parse webhook payload
    var webhook xaman.WebhookPayload
    if err := json.NewDecoder(r.Body).Decode(&webhook); err != nil {
        http.Error(w, "Invalid payload", http.StatusBadRequest)
        return
    }

    // Handle the webhook
    switch webhook.Meta.Resolved {
    case "signed":
        fmt.Printf("✅ Transaction signed: %s\n", webhook.TxID)
    case "rejected":
        fmt.Printf("❌ Transaction rejected\n")
    }

    w.WriteHeader(http.StatusOK)
}

API Reference

Client Methods

Method	Description
New(apiKey, apiSecret string, opts ...Option)	Create new Xaman client
CreatePayload(req *PayloadRequest) (*PayloadResponse, error)	Create a new payload
GetPayload(uuid string) (*PayloadDetails, error)	Get payload by UUID
CancelPayload(uuid string) error	Cancel a payload
GetCuratedAssets() (*CuratedAssets, error)	Get curated assets list
GetKYCStatus(account string) (*KYCStatus, error)	Get KYC status for account

Supported Transaction Types

• ✅ Payment
• ✅ TrustSet
• ✅ OfferCreate
• ✅ OfferCancel
• ✅ DestinationTag
• ✅ SignIn
• ✅ And more...

Error Handling

The SDK provides structured error handling:

response, err := client.CreatePayload(payload)
if err != nil {
    var xamanErr *xaman.Error
    if errors.As(err, &xamanErr) {
        fmt.Printf("Xaman API Error: %s (Code: %d)\n", xamanErr.Message, xamanErr.Code)
    } else {
        fmt.Printf("Other error: %v\n", err)
    }
}

Examples

Check out the examples directory for complete working examples:

• Basic Payment
• Token Payment
• Trust Line
• Webhook Server
• Payload Monitoring

Testing

Run the test suite:

go test ./...

Run tests with coverage:

go test -race -coverprofile=coverage.txt -covermode=atomic ./...

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Requirements

• Go 1.23.2 or higher
• Valid Xaman API credentials

Resources

• Xaman Developer Documentation
• XRP Ledger Documentation
• Xaman App

Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This SDK is not officially maintained by Xaman. It's a community-driven project to make Xaman integration easier for Go developers.