A comprehensive Go client for the Kuma Exchange API. This SDK provides a simple and idiomatic way to interact with Kuma's REST API endpoints.
- Complete API coverage for all Kuma Exchange endpoints
- Strongly typed request and response models
- Support for both production and sandbox environments
- Comprehensive error handling
- EIP-712 typed data signing for authenticated endpoints
- Fluent builder patterns for parameter construction
- Context-aware requests with proper timeout handling
go get github.com/amiwrpremium/go-kumapackage main
import (
"context"
"fmt"
"log"
"time"
"github.com/amiwrpremium/go-kuma"
"github.com/amiwrpremium/go-kuma/enums"
"github.com/amiwrpremium/go-kuma/types"
)
func main() {
// Create a client with API key and wallet
client := kuma.NewClient(kuma.ClientOptions{
APIKey: "your-api-key",
APISecret: "your-api-secret",
WalletAddress: "0xYourWalletAddress",
WalletPrivateKey: "YourWalletPrivateKey",
Environment: kuma.Production, // Use kuma.Sandbox for testing
})
// Create a context with timeout
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
// Get exchange info
exchangeInfo, err := client.GetExchange(ctx)
if err != nil {
log.Fatalf("Failed to get exchange info: %v", err)
}
fmt.Printf("Exchange Info: %+v\n", exchangeInfo)
// Place a limit order
orderParams := types.NewOrderParams().
WithMarket("ETH-USD").
WithType(enums.OrderTypeLimit).
WithSide(enums.OrderSideBuy).
WithQuantity("0.1").
WithPrice("2000").
WithTimeInForce(enums.OrderTimeInForceGoodTilCanceled)
order, err := client.CreateOrder(ctx, orderParams)
if err != nil {
log.Fatalf("Failed to place order: %v", err)
}
fmt.Printf("Order placed: %+v\n", order)
}The Kuma API uses a combination of API keys and EIP-712 wallet signatures for authentication:
- Public endpoints: No authentication required
- Private endpoints: Require an API key and signature
- Order management: Requires wallet signature using EIP-712
This SDK automatically handles all authentication methods when provided with the appropriate credentials.
client := kuma.NewClient(kuma.ClientOptions{
// Required for authenticated endpoints
APIKey: "your-api-key",
APISecret: "your-api-secret",
// Required for wallet-signed endpoints (order management)
WalletAddress: "0xYourWalletAddress",
WalletPrivateKey: "YourWalletPrivateKey",
// Optional settings
DelegatedKey: "0xDelegatedKeyAddress", // For delegated signing
Environment: kuma.Production, // or kuma.Sandbox
HTTPClient: &http.Client{}, // Custom HTTP client
Debug: true, // Enable debug logging
})info, err := client.GetExchange(ctx)// Get all markets
markets, err := client.GetMarkets(ctx)
// Get a specific market
market, err := client.GetMarket(ctx, "ETH-USD")// Get all tickers
tickers, err := client.GetTickers(ctx)
// Get a specific ticker
ticker, err := client.GetTicker(ctx, "ETH-USD")// Get level 1 order book (default)
orderBook, err := client.GetOrderBook(ctx, "ETH-USD", nil)
// Get level 2 order book with custom depth
params := types.NewOrderBookParams().
WithLevel(2).
WithLimit(100)
orderBook, err := client.GetOrderBook(ctx, "ETH-USD", params)// Get candles with default parameters
candles, err := client.GetCandles(ctx, "ETH-USD", enums.CandleIntervalOneHour, nil)
// Get candles with custom parameters
params := types.NewCandleParams().
WithStart(time.Now().Add(-24*time.Hour).Unix() * 1000).
WithEnd(time.Now().Unix() * 1000).
WithLimit(100)
candles, err := client.GetCandles(ctx, "ETH-USD", enums.CandleIntervalFifteenMinutes, params)// Create a limit order
orderParams := types.NewOrderParams().
WithMarket("ETH-USD").
WithType(enums.OrderTypeLimit).
WithSide(enums.OrderSideBuy).
WithQuantity("0.1").
WithPrice("2000").
WithClientOrderID("my-order-123").
WithTimeInForce(enums.OrderTimeInForceGoodTilCanceled)
order, err := client.CreateOrder(ctx, orderParams)
// Create a market order
marketOrderParams := types.NewOrderParams().
WithMarket("ETH-USD").
WithType(enums.OrderTypeMarket).
WithSide(enums.OrderSideSell).
WithQuantity("0.1")
order, err := client.CreateOrder(ctx, marketOrderParams)// Cancel specific orders
resp, err := client.CancelOrdersByIDs(ctx, []string{"orderId1", "orderId2"}, "")
// Cancel all orders for a market
resp, err := client.CancelOrdersByMarket(ctx, "ETH-USD", "")
// Cancel all orders
resp, err := client.CancelAllOrders(ctx, "")// Get all orders for a wallet
orders, err := client.GetOrders(ctx, "0xYourWalletAddress", nil)
// Get orders with filters
params := types.NewGetOrdersParams().
WithMarket("ETH-USD").
WithClosed(false). // Only active orders
WithLimit(50)
orders, err := client.GetOrders(ctx, "0xYourWalletAddress", params)
// Get a specific order
order, err := client.GetOrderByID(ctx, "orderId", "0xYourWalletAddress")
// Or by client order ID
order, err := client.GetOrderByID(ctx, "client:myClientOrderId", "0xYourWalletAddress")// Get wallet with positions
wallets, err := client.GetWallets(ctx, "0xYourWalletAddress", nil)
// Get wallet without positions
includePositions := false
wallets, err := client.GetWallets(ctx, "0xYourWalletAddress", &includePositions)// Get all positions
positions, err := client.GetPositions(ctx, "0xYourWalletAddress", "")
// Get positions for a specific market
positions, err := client.GetPositions(ctx, "0xYourWalletAddress", "ETH-USD")// Get historical PnL with default parameters
pnl, err := client.GetHistoricalPnL(ctx, "0xYourWalletAddress", nil)
// Get historical PnL with custom parameters
params := types.NewHistoricalPnLParams().
WithStart(time.Now().Add(-7*24*time.Hour).Unix() * 1000).
WithEnd(time.Now().Unix() * 1000).
WithLimit(100)
pnl, err := client.GetHistoricalPnL(ctx, "0xYourWalletAddress", params)The SDK returns typed errors that can be handled appropriately:
resp, err := client.GetMarket(ctx, "INVALID-MARKET")
if err != nil {
// Check if it's an API error
if apiErr, ok := err.(kuma.ErrorResponse); ok {
fmt.Printf("API Error: Code=%s, Message=%s\n", apiErr.Code, apiErr.Message)
} else {
fmt.Printf("Other error: %v\n", err)
}
}client := kuma.NewClient(kuma.ClientOptions{
APIKey: "your-sandbox-api-key",
APISecret: "your-sandbox-api-secret",
WalletAddress: "0xYourTestWalletAddress",
WalletPrivateKey: "YourTestWalletPrivateKey",
Environment: kuma.Sandbox,
})Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.
This SDK is an unofficial client library for Kuma Exchange. It is not affiliated with, maintained, authorized, endorsed, or sponsored by Kuma Exchange or any of its affiliates. This project is maintained independently by the community and provided "as is" without warranty of any kind.
Trading cryptocurrencies involves significant risk and can result in the loss of your invested capital. You should not invest more than you can afford to lose and should ensure that you fully understand the risks involved. This SDK is a tool for interacting with the Kuma Exchange API, and proper usage, including secure handling of API keys and private keys, is the responsibility of the end user.
The creator and contributors of this SDK are not responsible for any financial losses or damages incurred while using this software. Users are advised to thoroughly test the SDK with small amounts or in a sandbox environment before deploying it in production.