C# SDK

dotnet add package Apilow.GameCoin

using Apilow.GameCoin;

using var gamecoin = new GameCoinClient(
    Environment.GetEnvironmentVariable("GAMECOIN_SECRET_KEY")!,
    new GameCoinOptions { BaseUrl = "https://gamecoin.apilow.com" });
Console.WriteLine(gamecoin.Environment); // test or live, read from the key

using var tuned = new GameCoinClient(
    Environment.GetEnvironmentVariable("GAMECOIN_SECRET_KEY")!,
    new GameCoinOptions
    {
        BaseUrl = "https://gamecoin.apilow.com",
        Timeout = TimeSpan.FromSeconds(10), // give up on an attempt after 10 seconds
        MaxRetries = 3,                     // retry up to three times, four attempts in all
    });
Console.WriteLine(tuned.Environment);

var player = PlayerRef.Ext("user-42");
Console.WriteLine(player); // ext:user-42

var profile = await gamecoin.Players.UpsertAsync(player, new PlayerProfile { DisplayName = "Alice", Country = "BE" });
var same = await gamecoin.Players.GetAsync(player);
Console.WriteLine($"{profile.Id == same.Id} {profile.ExternalId} {profile.Kind}"); // True user-42 external

// A one-hour token for the browser SDK of your game client
var token = await gamecoin.Players.CreateTokenAsync(player);
Console.WriteLine($"{token.Token.StartsWith("gc_pt_")} {token.ExpiresAt > DateTimeOffset.UtcNow}"); // True True

var cleared = await gamecoin.Players.UpsertAsync(player, new PlayerProfile { Clear = PlayerProfileFields.DisplayName });
Console.WriteLine($"{cleared.DisplayName ?? "null"} {cleared.Country}"); // null BE

var granted = await gamecoin.Wallet.GrantAsync(player, new GrantRequest { Currency = "gems", Amount = 100, Reason = "welcome_gift" });
Console.WriteLine($"{granted.Balance.Total} {granted.Balance.Currency}"); // 100 gems

var spent = await gamecoin.Wallet.SpendAsync(player, new SpendRequest { Currency = "gems", Amount = 30, Reason = "revive" });
Console.WriteLine($"{spent.Balance.Total} {spent.Entry.Type}"); // 70 spend

var reward = await gamecoin.Wallet.GrantAsync(player, new GrantRequest
{
    Currency = "gold",
    Amount = 25,
    Reason = "daily_reward",
    Metadata = new Dictionary<string, string> { ["day"] = "3" },
});
Console.WriteLine($"{reward.Entry.Type} {reward.Entry.BonusDelta} {reward.Balance.Total}"); // grant 25 25

var wallet = await gamecoin.Wallet.GetAsync(player);
foreach (var balance in wallet.Balances)
{
    Console.WriteLine($"{balance.Currency} {balance.Paid} {balance.Bonus} {balance.Total}");
}
// gems 0 70 70
// gold 0 25 25

var page = await gamecoin.Ledger.ListAsync(player, new LedgerQuery { Currency = "gems", Limit = 1 });
Console.WriteLine($"{page.Entries.Count} {page.NextCursor is not null}"); // 1 True

var older = await gamecoin.Ledger.ListAsync(player, new LedgerQuery { Currency = "gems", Limit = 1, Cursor = page.NextCursor });
Console.WriteLine(older.Entries[0].Type); // grant

await foreach (var entry in gamecoin.Ledger.IterateAsync(player, new LedgerQuery { Currency = "gems", Limit = 50 }))
{
    Console.WriteLine($"{entry.CreatedAt:u} {entry.Type} {entry.PaidDelta + entry.BonusDelta} {entry.BalanceAfter.Total}");
    if (entry.Type == LedgerEntryType.Grant)
    {
        break; // no further page is fetched
    }
}

var catalog = await gamecoin.Catalog.GetAsync();
Console.WriteLine(string.Join(", ", catalog.Items.Select(item => $"{item.Sku} ({item.Type})"))); // potion (consumable), fire-sword (durable)

var given = await gamecoin.Inventory.GrantAsync(player, new InventoryGrantRequest { Sku = "potion", Quantity = 3 });
Console.WriteLine(given.Quantity); // 3

var used = await gamecoin.Inventory.ConsumeAsync(player, new InventoryConsumeRequest { Sku = "potion" }); // Quantity defaults to 1
Console.WriteLine(used.Quantity); // 2

foreach (var item in await gamecoin.Inventory.ListAsync(player)) // owned items only (quantity above 0)
{
    Console.WriteLine($"{item.Sku} x{item.Quantity}"); // potion x2
}

var purchase = await gamecoin.Purchases.CreateAsync(player, new PurchaseRequest { Sku = "potion" });
Console.WriteLine($"{purchase.Balance.Total} {purchase.Item.Quantity} {purchase.Entry.Ref.ItemSku}"); // 50 3 potion

await gamecoin.Inventory.GrantAsync(player, new InventoryGrantRequest { Sku = "fire-sword" });
try
{
    await gamecoin.Inventory.GrantAsync(player, new InventoryGrantRequest { Sku = "fire-sword" }); // limited to one per player
}
catch (GameCoinException ex)
{
    Console.WriteLine(ex.Code == GameCoinErrorCodes.LimitReached); // True
}

var checkout = await gamecoin.Checkouts.CreateAsync(player, new CheckoutRequest
{
    PackSku = "gems-500",
    SuccessUrl = "https://example.com/shop/thanks", // where the player goes after paying
    CancelUrl = "https://example.com/shop",
    Country = "BE", // the buyer's country decides the VAT (EU countries only)
});
Console.WriteLine($"{checkout.Order.Status} {checkout.CheckoutUrl.StartsWith("http")}"); // pending True

var order = await gamecoin.Orders.GetAsync(checkout.Order.Id);
Console.WriteLine($"{order.Status} {order.AmountCents} {order.VatCents} {order.NetCents}"); // pending 499 87 412

try
{
    await gamecoin.Orders.RefundAsync(order.Id, new RefundRequest { Reason = "player request" });
}
catch (GameCoinException ex) when (ex.Code == GameCoinErrorCodes.Conflict)
{
    Console.WriteLine($"not refundable: {ex.Message}");
}

var options = new RequestOptions { IdempotencyKey = "quest-17:user-42" };
var grantRequest = new GrantRequest { Currency = "gems", Amount = 10 };
var first = await gamecoin.Wallet.GrantAsync(player, grantRequest, options);
var again = await gamecoin.Wallet.GrantAsync(player, grantRequest, options);
Console.WriteLine($"{first.Replayed} {again.Replayed} {first.Entry.Id == again.Entry.Id}"); // False True True

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
var latest = await gamecoin.Wallet.GetAsync(player, cts.Token);
Console.WriteLine(latest.Balances.Count); // 2

try
{
    await gamecoin.Wallet.SpendAsync(player, new SpendRequest { Currency = "gems", Amount = 1_000_000 });
}
catch (GameCoinException ex) when (ex.Code == GameCoinErrorCodes.InsufficientFunds)
{
    Console.WriteLine($"needs {ex.Details["required"].GetInt64()}, has {ex.Details["available"].GetInt64()}"); // needs 1000000, has 60
}
catch (GameCoinException ex) when (ex.Code == GameCoinErrorCodes.RateLimited)
{
    Console.WriteLine($"try again in {ex.RetryAfter}");
}

try
{
    await gamecoin.Wallet.GrantAsync(player, new GrantRequest { Currency = "gems", Amount = -5 });
}
catch (ArgumentException ex)
{
    Console.WriteLine(ex.GetType().Name); // ArgumentOutOfRangeException
}

using System.Net;
using System.Net.Http.Headers;

public sealed class FlakyHandler : HttpMessageHandler
{
    public List<string> Keys { get; } = new();

    protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        Keys.Add(request.Headers.GetValues("Idempotency-Key").Single());
        if (Keys.Count < 3)
        {
            var failure = new HttpResponseMessage(HttpStatusCode.BadGateway) { Content = new StringContent("Bad gateway") };
            failure.Headers.RetryAfter = new RetryConditionHeaderValue(TimeSpan.Zero);
            return Task.FromResult(failure);
        }

        const string body = """{"item": {"sku": "potion", "quantity": 1, "updatedAt": "2026-10-05T12:00:00.000Z"}}""";
        return Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(body) });
    }
}

var handler = new FlakyHandler();
using var offline = new GameCoinClient("gc_sk_test_" + new string('x', 40), new GameCoinOptions { HttpMessageHandler = handler });
var gift = await offline.Inventory.GrantAsync(player, new InventoryGrantRequest { Sku = "potion" });
Console.WriteLine($"{gift.Quantity} {handler.Keys.Count} {handler.Keys.Distinct().Count()}"); // 1 3 1

using var sandbox = new GameCoinClient(
    Environment.GetEnvironmentVariable("GAMECOIN_SECRET_KEY")!,
    new GameCoinOptions { BaseUrl = "https://gamecoin.apilow.com" });
var fresh = PlayerRef.Ext($"test-{Guid.NewGuid():N}");
var start = await sandbox.Wallet.GrantAsync(fresh, new GrantRequest { Currency = "gems", Amount = 100 });
Console.WriteLine(start.Balance.Total); // 100