Skip to main content
Type definitions for cryptographic keys, signatures, and related functionality in the NEAR API.

​
Overview

NEAR supports two elliptic curve cryptography algorithms:
  • Ed25519: Fast, secure, recommended for most use cases
  • Secp256k1: Used for Bitcoin and Ethereum compatibility
All cryptographic values are encoded as curve:base58 strings.

​
Public Keys

​
PublicKey

Union type for all supported public key formats. 
type PublicKey = Ed25519PublicKey | Secp256k1PublicKey;

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

type Base58String = string;
Examples: 
// Ed25519 public key
const ed25519Key: PublicKey = 'ed25519:DcA2MzgpJbrUATQLLceocVckhhAqrkingax4oJ9kZ847';

// Secp256k1 public key
const secp256k1Key: PublicKey = 'secp256k1:5ftgm7wYK5gtVqq1kxMGy7gSudkrfYCbpsjL6sH1nwx2';

​
Usage

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

const keyPair = randomEd25519KeyPair();
const publicKey: PublicKey = keyPair.publicKey;

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

​
Private Keys

​
PrivateKey

Union type for all supported private key formats. 
type PrivateKey = Ed25519PrivateKey | Secp256k1PrivateKey;

type Ed25519PrivateKey = `ed25519:${Base58String}`;
type Secp256k1PrivateKey = `secp256k1:${Base58String}`;
Security Warning: Private keys should be stored securely and never exposed in client-side code or version control. Example: 
import { keyPair } from '@near-api/universal';

const privateKey: PrivateKey = 'ed25519:3D4YudU...';
const kp = keyPair(privateKey);

​
Signatures

​
Signature

Union type for all supported signature formats. 
type Signature = Ed25519Signature | Secp256k1Signature;

type Ed25519Signature = `ed25519:${Base58String}`;
type Secp256k1Signature = `secp256k1:${Base58String}`;
Example: 
import { randomEd25519KeyPair } from '@near-api/universal';

const keyPair = randomEd25519KeyPair();
const signOutput = keyPair.sign('48656c6c6f'); // "Hello" in hex

const signature: Signature = signOutput.signature;
console.log(signature); // "ed25519:..."

​
Curve Types

​
Curve

type Curve = 'ed25519' | 'secp256k1';

type Ed25519Curve = 'ed25519';
type Secp256k1Curve = 'secp256k1';
Example: 
const curve: Curve = 'ed25519';

​
CurveString

Generic format for curve-prefixed base58 strings. 
type CurveString = Ed25519CurveString | Secp256k1CurveString;

type Ed25519CurveString = `ed25519:${Base58String}`;
type Secp256k1CurveString = `secp256k1:${Base58String}`;

​
Native Types

Internal binary representations used for serialization.

​
NativePublicKey

type NativePublicKey = 
  | NativeEd25519PublicKey 
  | NativeSecp256k1PublicKey;

type NativeEd25519PublicKey = {
  ed25519Key: { data: Uint8Array };
};

type NativeSecp256k1PublicKey = {
  secp256k1Key: { data: Uint8Array };
};
These types are used internally for Borsh serialization and are not typically used in application code.

​
NativeSignature

type NativeSignature = 
  | NativeEd25519Signature 
  | NativeSecp256k1Signature;

type NativeEd25519Signature = {
  ed25519Signature: { data: Uint8Array };
};

type NativeSecp256k1Signature = {
  secp256k1Signature: { data: Uint8Array };
};

​
Message Types

​
Hex

Data for signing can be either raw bytes or hexadecimal string. 
type Hex = Uint8Array | string;
Examples: 
import { randomEd25519KeyPair } from '@near-api/universal';

const keyPair = randomEd25519KeyPair();

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

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

​
Key Pair Types

See Key Pair Helpers for key pair creation functions.

​
KeyPair

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

​
Sign Functions

type Sign = (message: Hex) => SignOutput;
type SafeSign = (message: Hex) => Result<SignOutput, SignError>;

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

​
Format Specifications

​
Base58 Encoding

NEAR uses Bitcoin’s Base58 alphabet: 
123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
Note: The characters 0, O, I, and l are excluded to avoid confusion.

​
Key Lengths

Ed25519:
  • Private key: 64 bytes (32 bytes secret + 32 bytes public)
  • Public key: 32 bytes
  • Signature: 64 bytes
Secp256k1:
  • Private key: 64 bytes (32 bytes secret + 32 bytes public)
  • Public key: 64 bytes (uncompressed without 0x04 header)
  • Signature: 64 bytes

​
Examples

​
Working with Keys

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

// Generate Ed25519 key pair
const ed25519Kp = randomEd25519KeyPair();
console.log('Public key:', ed25519Kp.publicKey);
console.log('Private key:', ed25519Kp.privateKey);

// Generate Secp256k1 key pair
const secp256k1Kp = randomSecp256k1KeyPair();
console.log('Public key:', secp256k1Kp.publicKey);
console.log('Private key:', secp256k1Kp.privateKey);

// Restore from private key
const restoredKp = keyPair(ed25519Kp.privateKey);

​
Signing Messages

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

const keyPair = randomEd25519KeyPair();

// Sign a message (hex string)
const message = '48656c6c6f'; // "Hello" in hex
const { signature, curve, u8Signature } = keyPair.sign(message);

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

​
Type Guards

function getCurve(key: PublicKey): Curve {
  if (key.startsWith('ed25519:')) {
    return 'ed25519';
  } else if (key.startsWith('secp256k1:')) {
    return 'secp256k1';
  }
  throw new Error('Invalid key format');
}

const publicKey: PublicKey = 'ed25519:...';
console.log(getCurve(publicKey)); // "ed25519"

​
Extracting Curve from Key

function extractCurveAndData(key: PublicKey): [Curve, string] {
  const [curve, data] = key.split(':') as [Curve, string];
  return [curve, data];
}

const publicKey: PublicKey = 'ed25519:DcA2MzgpJbrUATQLLceocVckhhAqrkingax4oJ9kZ847';
const [curve, base58Data] = extractCurveAndData(publicKey);

console.log('Curve:', curve);     // "ed25519"
console.log('Data:', base58Data); // "DcA2MzgpJbrUATQLLceocVckhhAqrkingax4oJ9kZ847"

​
Algorithm Comparison

FeatureEd25519Secp256k1
SpeedFasterSlower
Signature Size64 bytes64 bytes
Public Key Size32 bytes64 bytes
SecurityHighHigh
Use CaseDefaultEthereum compatibility

​
Best Practices

  1. Use Ed25519 by default: It’s faster and produces smaller keys
  2. Never expose private keys: Store securely, never commit to version control
  3. Use safe variants: Prefer safeSign() for better error handling
  4. Validate key format: Always validate curve prefix when accepting keys from external sources
  5. Key rotation: Consider rotating keys periodically for enhanced security