VenlyAPI.Core 3.1.0

VenlyAPI.Core for .NET (Server/Backend)

VenlyAPI.Core is the official .NET client for Venly's backend services. It provides typed access to Venly Wallet, Token, and Pay APIs with first-class async support and a simple initialization model for server-side apps and services.

• Wallet: users, wallets, balances, transactions, NFTs, signatures
• Token: ERC-20 and ERC-1155 contracts, minting, media, metadata
• Pay: fiat on/off ramp providers, checkout sessions, webhooks

Requirements

• .NET 6.0 or .NET Standard 2.1

Install

dotnet add package VenlyAPI.Core

Or include a PackageReference:

<ItemGroup>
  <PackageReference Include="VenlyAPI.Core" Version="x.y.z" />
</ItemGroup>

Quickstart

Initialize the API with your client credentials and desired environment.

using Venly;
using Venly.Backends;
using Venly.Models.Shared;

var clientId = Environment.GetEnvironmentVariable("VENLY_CLIENT_ID");
var clientSecret = Environment.GetEnvironmentVariable("VENLY_CLIENT_SECRET");

// Provided server-side provider using OAuth2 client credentials
var provider = new DefaultServerProvider(clientId, clientSecret);

// Initialize and verify authentication (throws on error)
await VenlyAPI.Initialize(provider, eVyEnvironment.Sandbox).AwaitResult();

// Optional: retrieve API info (version/environment)
var info = VenlyAPI.GetApiInfo();
Console.WriteLine($"Venly Core {info.CoreVersion} on {info.ActiveEnvironment}");

Calling patterns

Use await with exceptions on failure, or callback-style chaining.

• Await pattern (throws VyException on failure):

var wallet = await VenlyAPI.Wallet.GetWallet("<wallet-id>").AwaitResult();

• Callback chaining (no exceptions, handle success/fail explicitly):

VenlyAPI.Wallet.GetWallet("<wallet-id>")
    .OnSuccess(w => Console.WriteLine(w.Id))
    .OnFail(ex => Console.Error.WriteLine(ex.Message))
    .Finally(() => Console.WriteLine("Done"));

Signing methods (VyUserAuth)

Some endpoints require a user signing method to authorize the call (PIN, Password, Biometric, etc.). Provide both the SigningMethod ID and its corresponding value via VyUserAuth.

• Create a VyUserAuth from the user's PIN signing method:

using Venly.Models.Shared;
using Venly.Models.Wallet; // for TryGetPinAuth extension and models

var user = await VenlyAPI.Wallet.GetUser("<user-id>").AwaitResult();

// Option A: helper extension to build VyUserAuth from the user's PIN
if (!user.TryGetPinAuth("123456", out var userAuth))
    throw new InvalidOperationException("User has no PIN signing method configured.");

// Option B: manual construction from a specific signing method
// var pinMethod = user.SigningMethods.First(m => m.Type == eVySigningMethodType.Pin);
// var userAuth = new VyUserAuth(pinMethod.Id, "123456");

• Use VyUserAuth in endpoints that require signing:

// Create a wallet for the user
var newWallet = await VenlyAPI.Wallet
    .CreateWallet(new VyCreateWalletRequest { /* chain, description, etc. */ }, userAuth)
    .AwaitResult();

// Execute a prepared/confirmed transaction
var txResult = await VenlyAPI.Wallet
    .ExecuteTransaction("<transaction-request-id>", new VyConfirmTransactionRequest { /* fields */ }, userAuth)
    .AwaitResult();

// Create and sign a signature request (e.g., message/EIP-712)
var sig = await VenlyAPI.Wallet
    .CreateSignature(new VyCreateSignatureRequest { /* message or typed data */ }, userAuth)
    .AwaitResult();

Note: VyUserAuth automatically maps to the required header format internally; you only need to pass it to methods that accept a VyUserAuth parameter.

Common operations

• Wallet: get native balance by address

using Venly.Models.Shared;

var balance = await VenlyAPI.Wallet
    .GetNativeBalance(eVyChain.Ethereum, "0xYourAddress")
    .AwaitResult();

• Wallet: check transaction status

var status = await VenlyAPI.Wallet
    .GetTransactionStatus(eVyChain.Ethereum, "0xTxHash")
    .AwaitResult();

• Token: list your ERC-20 contracts

var contracts = await VenlyAPI.Token.GetErc20Contracts().AwaitResult();

• Pay: create a checkout session

var session = await VenlyAPI.Pay
    .CheckoutSession(new VyCheckoutSessionRequest { /* set fields */ })
    .AwaitResult();
Console.WriteLine(session.Url); // Send this URL to your end-user

Request/response DTOs like VyCheckoutSessionRequest, VyCreateWalletRequest, etc., are included under Venly.Models.* namespaces.

Environments

Select eVyEnvironment.Sandbox for testing and eVyEnvironment.Production for live usage when calling VenlyAPI.Initialize(...).

Error handling

• Await-style calls using .AwaitResult() throw on failure with a VyException containing API/HTTP context.
• Callback-style calls expose errors via .OnFail(Exception ex) without throwing.

Threading and schedulers

The SDK uses a custom task wrapper (VyTask/VyTask<T>). Server applications typically do not need special scheduler configuration. If needed, set a foreground scheduler with:

VenlyAPI.SetForegroundTaskScheduler(TaskScheduler.FromCurrentSynchronizationContext());

Security

• Treat clientSecret like a password. Do not embed secrets in client/mobile apps.
• Prefer secure secret storage (environment variables, key vaults, etc.).

Links

• Venly documentation: docs.venly.io

License

See LICENSE.txt in this repository.