Using the API with Wallet Authentication

When using the Nosana API with wallet authentication instead of an API key, you gain access to additional features like vault management for funding your deployments directly from your Solana wallet.

Overview

There are two ways to authenticate with the Nosana API:

1. API Key Authentication - Simple, uses credits from your account balance
2. Wallet Authentication - Uses your Solana wallet, enables vault management

Wallet authentication is required for:

• Creating and managing vaults
• Topping up vaults with SOL or NOS
• Withdrawing funds from vaults
• Getting vault balances

Using with @nosana/kit

The easiest way to use wallet authentication is with the @nosana/kit SDK, which automatically handles wallet signing and authentication.

For all the ways to create and configure a wallet (keypair files, base58 keys, browser wallets), see the Wallet Configuration guide.

Installation

npm install @nosana/kit

Initialization

Create the client without an API key and assign a wallet:

import { createNosanaClient, NosanaNetwork, loadWalletFromFile } from '@nosana/kit';

const client = createNosanaClient(NosanaNetwork.MAINNET);

// Load a Solana CLI keypair (defaults to ~/.config/solana/id.json)
client.wallet = await loadWalletFromFile();

When you use @nosana/kit with a wallet, it automatically:

• Creates SignerAuth from your wallet
• Handles message signing for authentication
• Provides Solana functions for vault operations

Creating Deployments with Vault

With a wallet (and no API key) configured, client.api is the signer variant of the API (NosanaApi), whose deployments include a vault:

const api = client.api as NosanaApi; // signer variant: deployments include a vault

const deployment = await api.deployments.create({
  name: 'My Deployment',
  market: 'CA5pMpqkYFKtme7K31pNB1s62X2SdhEv1nN9RdxKCpuQ',
  replicas: 1,
  timeout: 60,
  strategy: 'SIMPLE',
  job_definition: {
    version: '0.1',
    type: 'container',
    meta: { trigger: 'api' },
    ops: [
      {
        type: 'container/run',
        id: 'hello-world',
        args: {
          cmd: 'echo hello world',
          image: 'ubuntu',
        },
      },
    ],
  },
});

// The deployment includes a vault
console.log('Vault address:', deployment.vault.address);

For detailed information on managing vaults, see the Vault Management guide.

Using @nosana/api Directly

If you're using @nosana/api directly (without @nosana/kit), you need to provide SignerAuth yourself — an identifier (your wallet's public key), a message-signing function, and the Solana functions used for vault operations:

const signerAuth: SignerAuth = {
  identifier: wallet.address, // your wallet's public key
  generate: async (message: string) => {
    // Sign the message with your wallet and return it base64-encoded
    const signature = await wallet.signMessage(new TextEncoder().encode(message));
    return btoa(String.fromCharCode(...signature));
  },
  solana: {
    getBalance: async (address) => {
      // Fetch the SOL and NOS balances for the address
      return { SOL: 0, NOS: 0 };
    },
    transferTokensToRecipient: async (recipient, tokens) => {
      // Transfer the tokens from your wallet to the recipient
    },
    deserializeSignSendAndConfirmTransaction: async (transaction) => {
      // Sign, send, and confirm the serialized transaction
      return 'tx-signature';
    },
  },
};

const api = createNosanaApi(NosanaNetwork.MAINNET, signerAuth);

createNosanaApi and the SignerAuth type are also exported from the standalone @nosana/api package. @nosana/kit implements these functions for you from the configured wallet — that's the recommended path.

HTTP API with Wallet Authentication

If you're making direct HTTP requests, you need to:

1. Sign a message with your wallet
2. Include the signed message in the Authorization header
3. Include your public key in the x-user-id header

Authentication Header Format

Authorization: NosanaApiAuthentication:<base64-encoded-signature>
x-user-id: <your-wallet-public-key>

Example Request

# Sign the message "NosanaApiAuthentication" with your wallet
# Then include it in the Authorization header

curl -X POST https://dashboard.k8s.prd.nos.ci/api/deployments/vaults/create \
  -H "Authorization: NosanaApiAuthentication:<signed-message>" \
  -H "x-user-id: <your-public-key>" \
  -H "Content-Type: application/json"

For vault management endpoints and operations, see the Vault Management guide.

Differences from API Key Authentication

Feature	API Key	Wallet Authentication
Authentication	Bearer <api-key>	NosanaApiAuthentication:<signed-message>
Funding	Uses account credits	Uses vault (SOL/NOS)
Vault Management	❌ Not available	✅ Full vault operations
Setup Complexity	Simple	Requires wallet setup