Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/near/near-api-ts/llms.txt

Use this file to discover all available pages before exploring further.

The key pair helpers provide functions for creating and working with cryptographic key pairs used for signing transactions on the NEAR network.

​
Overview

NEAR supports two elliptic curve cryptography algorithms:
  • Ed25519: Default and recommended for most use cases
  • Secp256k1: Used for Bitcoin and Ethereum compatibility
The library provides both “safe” variants (return Result types) and “throwable” variants (throw errors) for all functions.

​
Functions

​
keyPair()

Creates a KeyPair from an existing private key string. 
import { keyPair } from '@near-api/universal';

const kp = keyPair('ed25519:3D4YudUahN1ktKQH4L8qk4GvBRX1M9aUE6VSVWPN1nX8B...');

console.log(kp.publicKey);  // "ed25519:..."
console.log(kp.privateKey); // "ed25519:..."

// Sign a message
const signature = kp.sign('48656c6c6f'); // "Hello" in hex
console.log(signature.signature); // "ed25519:..."
Parameters:
  • privateKey (string): Private key in curve:base58 format (e.g., "ed25519:..." or "secp256k1:...")
Returns: KeyPair Safe variant: safeKeyPair()

​
randomEd25519KeyPair()

Generates a new random Ed25519 key pair. 
import { randomEd25519KeyPair } from '@near-api/universal';

const kp = randomEd25519KeyPair();

console.log(kp.publicKey);  // "ed25519:..."
console.log(kp.privateKey); // "ed25519:..."
Returns: KeyPair Safe variant: safeRandomEd25519KeyPair()

​
randomSecp256k1KeyPair()

Generates a new random Secp256k1 key pair. 
import { randomSecp256k1KeyPair } from '@near-api/universal';

const kp = randomSecp256k1KeyPair();

console.log(kp.publicKey);  // "secp256k1:..."
console.log(kp.privateKey); // "secp256k1:..."
Returns: KeyPair Safe variant: safeRandomSecp256k1KeyPair()

​
KeyPair Object

The KeyPair object provides the following properties and methods:

​
Properties

  • publicKey (PublicKey): Public key in curve:base58 format
  • privateKey (PrivateKey): Private key in curve:base58 format

​
Methods

​
sign()

Signs a message and returns the signature. 
const kp = randomEd25519KeyPair();

// Sign hex string
const sig1 = kp.sign('48656c6c6f');

// Sign Uint8Array
const sig2 = kp.sign(new Uint8Array([72, 101, 108, 108, 111]));

console.log(sig1.signature); // "ed25519:..."
console.log(sig1.curve);     // "ed25519"
console.log(sig1.u8Signature); // Uint8Array
Parameters:
  • message (Hex): Message to sign (Uint8Array or hex string)
Returns: SignOutput
  • signature (Signature): Signature in curve:base58 format
  • curve (Curve): Curve type ("ed25519" or "secp256k1")
  • u8Signature (Uint8Array): Raw signature bytes
Safe variant: safeSign()

​
Type Definitions

​
KeyPair

type KeyPair = {
  publicKey: PublicKey;
  privateKey: PrivateKey;
  sign: Sign;
  safeSign: SafeSign;
};

​
PublicKey & PrivateKey

type PublicKey = Ed25519PublicKey | Secp256k1PublicKey;
type PrivateKey = Ed25519PrivateKey | Secp256k1PrivateKey;

type Ed25519PublicKey = `ed25519:${Base58String}`;
type Secp256k1PublicKey = `secp256k1:${Base58String}`;

​
SignOutput

type SignOutput = {
  signature: Signature;
  curve: Curve;
  u8Signature: Uint8Array;
};

type Signature = Ed25519Signature | Secp256k1Signature;
type Curve = 'ed25519' | 'secp256k1';
See Crypto Types for complete type information.

​
Examples

​
Creating Key Pairs

import { 
  keyPair, 
  randomEd25519KeyPair, 
  randomSecp256k1KeyPair 
} from '@near-api/universal';

// From existing private key
const existingKp = keyPair('ed25519:...');

// Generate new Ed25519 key pair (recommended)
const ed25519Kp = randomEd25519KeyPair();

// Generate new Secp256k1 key pair
const secp256k1Kp = randomSecp256k1KeyPair();

​
Signing Messages

import { randomEd25519KeyPair } from '@near-api/universal';

const kp = randomEd25519KeyPair();

// Sign a message
const message = 'Hello NEAR!';
const hexMessage = Buffer.from(message).toString('hex');
const signature = kp.sign(hexMessage);

console.log('Signature:', signature.signature);
console.log('Curve:', signature.curve);

​
Safe Operations

import { safeKeyPair } from '@near-api/universal';

const result = safeKeyPair('ed25519:...');

if (result.ok) {
  const kp = result.value;
  const sig = kp.safeSign('48656c6c6f');
  
  if (sig.ok) {
    console.log(sig.value.signature);
  } else {
    console.error('Sign error:', sig.error);
  }
} else {
  console.error('KeyPair error:', result.error);
}

​
Using with Memory Signer

import { 
  createMemorySigner, 
  randomEd25519KeyPair 
} from '@near-api/universal';

const kp = randomEd25519KeyPair();

const signer = createMemorySigner({
  accountId: 'alice.near',
  keyPair: kp
});

​
Key Storage

import { randomEd25519KeyPair } from '@near-api/universal';

const kp = randomEd25519KeyPair();

// Store private key securely (e.g., encrypted)
const privateKeyToStore = kp.privateKey;

// Later, recreate the key pair
const restoredKp = keyPair(privateKeyToStore);

​
Security Considerations

  1. Never expose private keys: Private keys should be stored securely and never committed to version control
  2. Use Ed25519 by default: Ed25519 is faster and produces smaller signatures
  3. Key rotation: Consider rotating keys periodically for enhanced security
  4. Secure storage: Use hardware security modules (HSMs) or secure enclaves for production keys

​
Error Handling

Common errors:
  • Invalid private key format: Key must be in curve:base58 format
  • Invalid curve: Only ed25519 and secp256k1 are supported
  • Malformed base58: The base58 portion must be valid
import { safeKeyPair } from '@near-api/universal';

const result = safeKeyPair('invalid-key');

if (!result.ok) {
  console.error(result.error.kind); // "CreateKeyPair.Args.InvalidSchema"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us