Skip to main content

API Reference

Complete reference for the @7n7d/sdk package.

Installation​

npm install @7n7d/sdk

SevenNSevenD (Main Client)​

The main entry point. Creates API and on-chain sub-clients.

import { SevenNSevenD } from '@7n7d/sdk';

const client = new SevenNSevenD({
  apiKey: 'your-api-key',
  network: 'testnet',          // 'testnet' | 'mainnet'
  privateKey: '0x...',         // Required for on-chain transactions
});

SevenNSevenDConfig​

PropertyTypeRequiredDescription
apiKeystringYesAPI key for the 7N7D REST API
apiUrlstringNoOverride the default API URL
rpcUrlstringNoOverride the default RPC endpoint
privateKeystringNoPrivate key for signing on-chain transactions
network'testnet' | 'mainnet'NoNetwork selection (default: 'testnet')

Sub-Clients​

PropertyTypeDescription
apiApiClientREST API client (status, positions, chat)
vaultVaultClientTrading vault on-chain operations
stakingStakingClientToken staking on-chain operations
tokenTokenClient7N7D token on-chain operations

ApiClient​

REST API client for querying the 7N7D backend. Accessed via client.api.

Methods​

api.status()​

Get vault and agent status.

const { data } = await client.api.status();
// data: { vault: { status, network }, agent: { status, positions }, timestamp }

Returns: Promise<ApiResponse<StatusData>>

api.positions()​

List open trading positions.

const { data } = await client.api.positions();
// data: { positions: Position[], timestamp }

Returns: Promise<ApiResponse<PositionsData>>

api.balance(address)​

Get balance information for an address.

const { data } = await client.api.balance('0x...');
// data: { address, network, contracts: { tradingVault, token, usdc }, timestamp }

Returns: Promise<ApiResponse<BalanceData>>

api.chat(message, walletAddress?, conversationHistory?)​

Send a message to the AI agent.

const { data } = await client.api.chat('What is the current TVL?');
// data: { response, intent, action, timestamp }
ParameterTypeRequiredDescription
messagestringYesUser message
walletAddressstringNoWallet for context
conversationHistoryArray<{ role: string; content: string }>NoPrevious messages

Returns: Promise<ApiResponse<ChatData>>

api.contracts()​

Get deployed contract addresses and network info.

const { data } = await client.api.contracts();
// data: { network, chainId, contracts: { tradingVault, token, usdc, profitDistributor, governanceDao }, rpcUrl, explorerUrl, timestamp }

Returns: Promise<ApiResponse<ContractsData>>

api.health()​

Health check endpoint.

const health = await client.api.health();
// { ok: true, service: '7n7d-api', version: '...', timestamp: '...' }

Returns: Promise<HealthData>

VaultClient​

On-chain trading vault operations. Accessed via client.vault.

note

Methods that write to the blockchain (deposit, withdraw) require a privateKey in the client config.

Methods​

vault.deposit(amount)​

Deposit USDC into the trading vault. Automatically approves USDC spending first.

const result = await client.vault.deposit('1000'); // 1000 USDC
// { txHash: '0x...', explorerLink: 'https://...' }
ParameterTypeDescription
amountstringUSDC amount in human-readable units

Returns: Promise<{ txHash: string; explorerLink: string }>

vault.withdraw(shares)​

Request withdrawal of vault shares.

const result = await client.vault.withdraw('100'); // 100 shares
// { txHash: '0x...', explorerLink: 'https://...' }
ParameterTypeDescription
sharesstringShare amount in human-readable units

Returns: Promise<{ txHash: string; explorerLink: string }>

vault.balance(address)​

Get vault share balance for an address.

const shares = await client.vault.balance('0x...');
// '1234.567890123456789'

Returns: Promise<string> — Human-readable share balance.

vault.sharePrice()​

Get current share price (USDC per 1 share).

const price = await client.vault.sharePrice();
// '1.023456'

Returns: Promise<string> — Human-readable USDC value per share.

vault.totalAssets()​

Get total vault TVL in USDC.

const tvl = await client.vault.totalAssets();
// '50000.000000'

Returns: Promise<string> — Human-readable USDC total.

vault.withdrawalRequest(address)​

Check withdrawal request status for an address.

const req = await client.vault.withdrawalRequest('0x...');
// { shares: 100n, requestTime: 1711900000n, processed: false }

Returns: Promise<WithdrawalRequest>

interface WithdrawalRequest {
  shares: bigint;
  requestTime: bigint;
  processed: boolean;
}

StakingClient​

Token staking operations via the ProfitDistributor contract. Accessed via client.staking.

note

Methods that write to the blockchain (stake, unstake, claim) require a privateKey in the client config.

Methods​

staking.stake(amount)​

Stake 7N7D tokens. Automatically approves token spending first.

const result = await client.staking.stake('5000'); // 5000 7N7D
// { txHash: '0x...', explorerLink: 'https://...' }

Returns: Promise<{ txHash: string; explorerLink: string }>

staking.unstake(amount)​

Unstake 7N7D tokens.

const result = await client.staking.unstake('5000');
// { txHash: '0x...', explorerLink: 'https://...' }

Returns: Promise<{ txHash: string; explorerLink: string }>

staking.earned(address)​

Get pending USDC rewards for an address.

const rewards = await client.staking.earned('0x...');
// '42.500000'

Returns: Promise<string> — Human-readable USDC rewards.

staking.claim()​

Claim pending USDC staking rewards.

const result = await client.staking.claim();
// { txHash: '0x...', explorerLink: 'https://...' }

Returns: Promise<{ txHash: string; explorerLink: string }>

staking.balance(address)​

Get staked 7N7D token balance for an address.

const staked = await client.staking.balance('0x...');
// '5000.000000000000000000'

Returns: Promise<string> — Human-readable staked token balance.

TokenClient​

7N7D token operations. Accessed via client.token.

Methods​

token.balance(address)​

Get 7N7D token balance for an address.

const balance = await client.token.balance('0x...');
// '10000.000000000000000000'

Returns: Promise<string> — Human-readable token balance.

token.approve(spender, amount)​

Approve a spender to use 7N7D tokens.

const result = await client.token.approve('0xSpender...', '5000');
// { txHash: '0x...', explorerLink: 'https://...' }
ParameterTypeDescription
spenderstringAddress to approve
amountstringToken amount in human-readable units

Returns: Promise<{ txHash: string; explorerLink: string }>

Exported Types​

All types are importable from @7n7d/sdk:

import {
  type SevenNSevenDConfig,
  type ApiResponse,
  type StatusData,
  type Position,
  type PositionsData,
  type BalanceData,
  type ChatData,
  type ContractsData,
  type HealthData,
  type WithdrawalRequest,
  // Delegation (ERC-7710)
  DelegationClient,
  type DelegationClientConfig,
  type Caveat,
  type Delegation,
  type DelegationResult,
  type DelegationStatus,
  type VaultDepositDelegationConfig,
  CAVEAT_ENFORCERS,
  DELEGATION_EIP712_DOMAIN,
  ROOT_AUTHORITY,
  // Errors
  SdkError,
  ApiError,
  ContractError,
  ConfigError,
} from '@7n7d/sdk';

ApiResponse<T>​

interface ApiResponse<T = unknown> {
  ok: boolean;
  data: T;
}

Error Classes​

All errors extend SdkError:

ClassCodeDescription
SdkError(varies)Base error class
ApiErrorAPI_ERRORREST API request failure (includes HTTP status)
ContractErrorCONTRACT_ERROROn-chain transaction failure
ConfigErrorCONFIG_ERRORInvalid client configuration
try {
  await client.vault.deposit('1000');
} catch (error) {
  if (error instanceof ApiError) {
    console.log(error.status);  // HTTP status code
  }
  if (error instanceof SdkError) {
    console.log(error.code);    // Error code string
    console.log(error.message); // Human-readable message
    console.log(error.cause);   // Underlying error (if any)
  }
}

Exported Constants​

import { NETWORKS, DECIMALS, API_PATHS } from '@7n7d/sdk';

NETWORKS​

Pre-configured network settings for testnet and mainnet.

const NETWORKS: {
  testnet: NetworkConfig;
  mainnet: NetworkConfig;
};

interface NetworkConfig {
  chainId: number;              // e.g. 11155111 (Sepolia)
  name: string;                 // e.g. "Sepolia"
  rpcUrl: string;               // JSON-RPC endpoint
  explorerUrl: string;          // Block explorer base URL
  apiUrl: string;               // 7N7D API base URL
  contracts: {
    token: string;              // 7N7D token address
    usdc: string;               // USDC token address
    profitDistributor: string;  // Staking rewards contract
    tradingVault: string;       // Trading vault contract
    governanceDao: string;      // Governance DAO contract
  };
}

Usage:

import { NETWORKS } from '@7n7d/sdk';

// Get testnet vault address
const vaultAddress = NETWORKS.testnet.contracts.tradingVault;

// Get RPC URL for direct provider setup
const rpcUrl = NETWORKS.testnet.rpcUrl;
tip

You typically don't need to access NETWORKS directly — the SevenNSevenD client resolves network config automatically from the network option.

DECIMALS​

Token decimal constants used for parsing and formatting on-chain values.

KeyValueDescription
USDC6USDC decimal places
TOKEN187N7D token decimals
SHARES18Vault share decimals

Usage:

import { DECIMALS } from '@7n7d/sdk';
import { parseUnits, formatUnits } from 'viem';

// Parse 1000 USDC to on-chain units
const amount = parseUnits('1000', DECIMALS.USDC); // 1000000000n

// Format vault shares from on-chain units
const shares = formatUnits(rawShares, DECIMALS.SHARES);

API_PATHS​

REST API endpoint paths used internally by ApiClient. Exported for custom integrations.

KeyPathDescription
status/api/v1/agent/statusVault and agent status
positions/api/v1/agent/positionsOpen trading positions
balance/api/v1/agent/balanceAddress balance information
chat/api/v1/agent/chatAI agent chat endpoint
contracts/api/v1/agent/contractsDeployed contract addresses
health/api/v1/agent/healthHealth check

Usage:

import { API_PATHS, NETWORKS } from '@7n7d/sdk';

// Build a custom request URL
const url = `${NETWORKS.testnet.apiUrl}${API_PATHS.status}`;
const response = await fetch(url);

Exported ABIs​

Contract ABIs for direct use with ethers.js, viem, or any EVM library. Use these when you need low-level contract access beyond what the SDK clients provide.

import {
  TRADING_VAULT_ABI,
  USDC_ABI,
  TOKEN_ABI,
  PROFIT_DISTRIBUTOR_ABI,
} from '@7n7d/sdk';
ABIContractDescription
TRADING_VAULT_ABITradingVaultTrading vault — deposit USDC, withdraw shares, view TVL
USDC_ABIUSDC (ERC-20)Standard ERC-20 for USDC approve/transfer operations
TOKEN_ABI7N7D Token (ERC-20)7N7D governance token — transfer, approve, burn
PROFIT_DISTRIBUTOR_ABIProfitDistributorStaking rewards — stake, unstake, claim USDC rewards

Usage with viem:

import { createPublicClient, http } from 'viem';
import { sepolia } from 'viem/chains';
import { TRADING_VAULT_ABI, NETWORKS } from '@7n7d/sdk';

const client = createPublicClient({ chain: sepolia, transport: http() });

const tvl = await client.readContract({
  address: NETWORKS.testnet.contracts.tradingVault as `0x${string}`,
  abi: TRADING_VAULT_ABI,
  functionName: 'totalAssets',
});

Need Help?​