Vault Management
When using wallet authentication, each deployment has an associated vault that holds funds (SOL and NOS) for running jobs. Vaults allow you to manage deployment funding directly from your Solana wallet.
Overview
Vaults are Solana accounts that hold SOL and NOS tokens used to pay for deployment execution. Each deployment created with wallet authentication automatically gets a vault, but you can also create and manage vaults independently.
Getting Started
To use vault management, you need to authenticate with a wallet. See the Wallet Authentication guide for setup instructions.
With a wallet (and no API key) configured, client.api is the signer variant of the API (NosanaApi), whose deployments include a vault:
import { function createNosanaClient(network: NosanaNetwork | undefined, customConfig: PartialClientConfig & {
connect: ConnectFactoryConfig & {
clientSecret: string;
};
}): NosanaClient & {
connect: ServerConnect;
} (+3 overloads)
createNosanaClient, type NosanaNetwork = "mainnet" | "devnet" | "localnet"
const NosanaNetwork: {
readonly MAINNET: "mainnet";
readonly DEVNET: "devnet";
readonly LOCALNET: "localnet";
}
NosanaNetwork, function loadWalletFromFile(filePath?: string): Promise<Wallet>Load a wallet from a Solana CLI keypair JSON file.
Reads a JSON file containing a byte array (as used by `solana-keygen`)
and creates a wallet from it. Defaults to `~/.config/solana/id.json`
if no path is provided.loadWalletFromFile } from '@nosana/kit';
import type { NosanaApi } from '@nosana/kit';
const const client: NosanaClientclient = function createNosanaClient(network?: NosanaNetwork, customConfig?: PartialClientConfig): NosanaClient (+3 overloads)createNosanaClient(const NosanaNetwork: {
readonly MAINNET: "mainnet";
readonly DEVNET: "devnet";
readonly LOCALNET: "localnet";
}
NosanaNetwork.type MAINNET: "mainnet"MAINNET);
const client: NosanaClientclient.NosanaClient.wallet: Wallet | undefinedThe wallet. Must be a Wallet (supports both message and transaction signing).
Set this property directly to configure the wallet.wallet = await function loadWalletFromFile(filePath?: string): Promise<Wallet>Load a wallet from a Solana CLI keypair JSON file.
Reads a JSON file containing a byte array (as used by `solana-keygen`)
and creates a wallet from it. Defaults to `~/.config/solana/id.json`
if no path is provided.loadWalletFromFile();
const const api: NosanaApiapi = const client: NosanaClientclient.NosanaClient.api: NosanaApiClientapi as NosanaApi; // signer variant: deployments include a vaultDeployment Vaults
When you create a deployment with wallet authentication, it automatically includes a vault:
const const deployment: Deploymentdeployment = await const api: NosanaApiapi.NosanaApi.deployments: DeploymentsApideployments.DeploymentsApi.create: (deploymentBody: CreateDeployment) => Promise<Deployment>create({
name: stringname: 'My Deployment',
market?: string | undefinedmarket: 'CA5pMpqkYFKtme7K31pNB1s62X2SdhEv1nN9RdxKCpuQ',
replicas: numberreplicas: 1,
timeout: numbertimeout: 60,
strategy: "SIMPLE" | "SIMPLE-EXTEND" | "SCHEDULED" | "INFINITE"strategy: 'SIMPLE',
job_definition: JobDefinitionjob_definition: {
version: stringversion: '0.1',
type?: string | undefinedtype: 'container',
meta?: Meta | undefinedmeta: { trigger?: string | undefinedtrigger: 'api' },
ops: Opsops: [
{
type: keyof OperationArgsMaptype: 'container/run',
id: OperationIdid: 'hello-world',
args: ContainerRun | ContainerCreateVolume | VmRunArgsargs: {
cmd: stringcmd: 'echo hello world',
image: stringimage: 'ubuntu',
},
},
],
},
});
// The deployment includes a vault
var console: ConsoleThe `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:
* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v24.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v24.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module.
_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v24.x/api/process.html#a-note-on-process-io) for
more information.
Example using the global `console`:
```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```
Example using the `Console` class:
```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```console.Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)Prints to `stdout` with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html)
(the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v24.x/api/util.html#utilformatformat-args)).
```js
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
```
See [`util.format()`](https://nodejs.org/docs/latest-v24.x/api/util.html#utilformatformat-args) for more information.log('Vault address:', const deployment: Deploymentdeployment.vault: string & Vaultvault.Vault.address: stringaddress);Vault Operations
Get Vault Balance
Check the current balance of SOL and NOS in your vault:
const const balance: {
SOL: number;
NOS: number;
}
balance = await const deployment: Deploymentdeployment.vault: string & Vaultvault.Vault.getBalance: () => Promise<{
SOL: number;
NOS: number;
}>
getBalance();
var console: ConsoleThe `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:
* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v24.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v24.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module.
_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v24.x/api/process.html#a-note-on-process-io) for
more information.
Example using the global `console`:
```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```
Example using the `Console` class:
```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```console.Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)Prints to `stdout` with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html)
(the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v24.x/api/util.html#utilformatformat-args)).
```js
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
```
See [`util.format()`](https://nodejs.org/docs/latest-v24.x/api/util.html#utilformatformat-args) for more information.log(`SOL: ${const balance: {
SOL: number;
NOS: number;
}
balance.type SOL: numberSOL}, NOS: ${const balance: {
SOL: number;
NOS: number;
}
balance.type NOS: numberNOS}`);The balance is returned as an object with SOL and NOS properties, representing the amounts in each token.
Note: Getting vault balance is handled client-side using Solana RPC calls, not through a direct API endpoint.
Top Up Vault
Add funds to your vault to pay for deployment execution. You can top up with SOL, NOS, or both:
// Top up with NOS tokens
await const deployment: Deploymentdeployment.vault: string & Vaultvault.Vault.topup: (options: TopupVaultOptions) => Promise<void>topup({
TopupVaultOptions.NOS?: number | undefinedNOS: 100, // Amount in NOS
});
// Top up with SOL
await const deployment: Deploymentdeployment.vault: string & Vaultvault.Vault.topup: (options: TopupVaultOptions) => Promise<void>topup({
TopupVaultOptions.SOL?: number | undefinedSOL: 0.5, // Amount in SOL
});
// Top up with both
await const deployment: Deploymentdeployment.vault: string & Vaultvault.Vault.topup: (options: TopupVaultOptions) => Promise<void>topup({
TopupVaultOptions.SOL?: number | undefinedSOL: 0.5,
TopupVaultOptions.NOS?: number | undefinedNOS: 100,
});The topup method transfers tokens from your wallet to the vault address. Make sure your wallet has sufficient balance before attempting to top up.
Note: Topping up a vault is handled client-side using Solana token transfers, not through a direct API endpoint.
Withdraw from Vault
Withdraw all funds from a vault back to your wallet:
await const deployment: Deploymentdeployment.vault: string & Vaultvault.Vault.withdraw: () => Promise<void>withdraw();This operation:
- Calls the API to generate a withdrawal transaction
- Signs the transaction with your wallet
- Sends and confirms the transaction on-chain
- Transfers all SOL and NOS from the vault back to your wallet
Managing Multiple Vaults
You can create and manage vaults independently of deployments:
Create a Vault
// Create a new vault
const const vault: Vaultvault = await const api: NosanaApiapi.NosanaApi.deployments: DeploymentsApideployments.DeploymentsApi.vaults: {
create: () => Promise<Vault>;
list: () => Promise<Vault[]>;
}
vaults.create: () => Promise<Vault>create();
var console: ConsoleThe `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:
* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v24.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v24.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module.
_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v24.x/api/process.html#a-note-on-process-io) for
more information.
Example using the global `console`:
```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```
Example using the `Console` class:
```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```console.Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)Prints to `stdout` with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html)
(the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v24.x/api/util.html#utilformatformat-args)).
```js
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
```
See [`util.format()`](https://nodejs.org/docs/latest-v24.x/api/util.html#utilformatformat-args) for more information.log('Vault address:', const vault: Vaultvault.Vault.address: stringaddress);
var console: ConsoleThe `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:
* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v24.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v24.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module.
_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v24.x/api/process.html#a-note-on-process-io) for
more information.
Example using the global `console`:
```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```
Example using the `Console` class:
```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```console.Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)Prints to `stdout` with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html)
(the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v24.x/api/util.html#utilformatformat-args)).
```js
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
```
See [`util.format()`](https://nodejs.org/docs/latest-v24.x/api/util.html#utilformatformat-args) for more information.log('Created at:', const vault: Vaultvault.Vault.created_at?: Date | undefinedcreated_at);List All Vaults
// List all your vaults
const const vaults: Vault[]vaults = await const api: NosanaApiapi.NosanaApi.deployments: DeploymentsApideployments.DeploymentsApi.vaults: {
create: () => Promise<Vault>;
list: () => Promise<Vault[]>;
}
vaults.list: () => Promise<Vault[]>list();
const vaults: Vault[]vaults.Array<Vault>.forEach(callbackfn: (value: Vault, index: number, array: Vault[]) => void, thisArg?: any): voidPerforms the specified action for each element in an array.forEach((vault: Vaultvault) => {
var console: ConsoleThe `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:
* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v24.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v24.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module.
_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v24.x/api/process.html#a-note-on-process-io) for
more information.
Example using the global `console`:
```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```
Example using the `Console` class:
```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```console.Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)Prints to `stdout` with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html)
(the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v24.x/api/util.html#utilformatformat-args)).
```js
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
```
See [`util.format()`](https://nodejs.org/docs/latest-v24.x/api/util.html#utilformatformat-args) for more information.log(`Vault: ${vault: Vaultvault.Vault.address: stringaddress}, Created: ${vault: Vaultvault.Vault.created_at?: Date | undefinedcreated_at}`);
});Use Vault Methods
Once you have a vault object, you can use all the same methods:
const const vault: Vaultvault = await const api: NosanaApiapi.NosanaApi.deployments: DeploymentsApideployments.DeploymentsApi.vaults: {
create: () => Promise<Vault>;
list: () => Promise<Vault[]>;
}
vaults.create: () => Promise<Vault>create();
// Check balance
const const balance: {
SOL: number;
NOS: number;
}
balance = await const vault: Vaultvault.Vault.getBalance: () => Promise<{
SOL: number;
NOS: number;
}>
getBalance();
// Top up
await const vault: Vaultvault.Vault.topup: (options: TopupVaultOptions) => Promise<void>topup({ TopupVaultOptions.NOS?: number | undefinedNOS: 50 });
// Withdraw
await const vault: Vaultvault.Vault.withdraw: () => Promise<void>withdraw();API Endpoints Summary
When using wallet authentication, you have access to these vault management endpoints:
| Operation | Endpoint | Method | Notes |
|---|---|---|---|
| Create Vault | /api/deployments/vaults/create | POST | Returns vault address |
| List Vaults | /api/deployments/vaults | GET | Returns all your vaults |
| Withdraw | /api/deployments/vaults/{vault}/withdraw | POST | Returns transaction to sign |
| Get Balance | N/A | N/A | Client-side Solana RPC call |
| Top Up | N/A | N/A | Client-side token transfer |
Note: The getBalance and topup operations are handled client-side using Solana RPC calls and token transfers, not through direct API endpoints.
Best Practices
- Monitor Vault Balance: Regularly check your vault balance to ensure you have sufficient funds for deployments
- Top Up Before Running: Add funds to your vault before starting deployments to avoid interruptions
- Withdraw Unused Funds: Periodically withdraw unused funds from vaults back to your wallet
- Use Separate Vaults: Consider creating separate vaults for different projects or environments