Stellar PHP SDK API Documentation

KeyPair
in package

Represents an Ed25519 public/private keypair for signing Stellar transactions

A KeyPair holds the cryptographic keys used to sign transactions and identify accounts on the Stellar network. Public keys are encoded as G... addresses (account IDs), while private keys are encoded as S... seeds.

Security Considerations:

  • Private keys (seeds) must be kept secure and never transmitted or stored in plain text
  • Use secure random generation for production keypairs
  • Consider hardware security modules (HSM) for high-value accounts
  • Private keys should be encrypted at rest
  • Never log or display private keys

Usage: // Generate a new random keypair $keyPair = KeyPair::random();

// Load from an existing seed $keyPair = KeyPair::fromSeed("SBXXX...");

// Sign a transaction $transaction->sign($keyPair, Network::testnet());

// Get the account ID (public key) $accountId = $keyPair->getAccountId(); // G...

Tags
see
https://developers.stellar.org

Stellar developer docs

since
1.0.0

Table of Contents

Methods

__construct()  : mixed
Creates a new KeyPair from raw key bytes
fromAccountId()  : KeyPair
Creates a KeyPair from a Stellar account ID (public key)
fromBip39SeedHex()  : KeyPair
Creates a KeyPair from a BIP-39 seed hex string using hierarchical deterministic derivation
fromMnemonic()  : KeyPair
Creates a KeyPair from a BIP-39 mnemonic phrase using hierarchical deterministic derivation
fromPrivateKey()  : KeyPair
Creates a KeyPair from raw 32-byte private key data
fromPublicKey()  : KeyPair
Creates a KeyPair from raw 32-byte public key data
fromSeed()  : KeyPair
Creates a KeyPair from a Stellar secret seed (private key)
getAccountId()  : string
Returns the base32-encoded account ID (public key)
getHint()  : string
Returns the signature hint (last 4 bytes of the public key)
getPrivateKey()  : string|null
Returns the raw 32-byte private key
getPublicKey()  : string
Returns the raw 32-byte public key
getPublicKeyChecksum()  : string
Returns the checksum bytes for the public key
getSecretSeed()  : string|null
Returns the base32-encoded secret seed (private key)
getXdrMuxedAccount()  : XdrMuxedAccount
Converts this keypair to an XDR muxed account
getXdrSignerKey()  : XdrSignerKey
Converts this keypair to an XDR signer key
random()  : KeyPair
Generates a new random KeyPair using cryptographically secure random bytes
sign()  : string|null
Signs data with the private key using Ed25519 signature algorithm
signDecorated()  : XdrDecoratedSignature|null
Signs data and returns a decorated signature with hint
signPayloadDecorated()  : XdrDecoratedSignature|null
Signs a payload and returns a decorated signature with XORed hint
str_to_stream()  : resource
Converts a string into a stream resource
verifySignature()  : bool
Verifies an Ed25519 signature against a message using this keypair's public key
getEd25519SecretKey()  : string|null
Derives the Ed25519 secret key from the seed

Methods

__construct()

Creates a new KeyPair from raw key bytes

public __construct(string $publicKey[, string|null $privateKey = null ]) : mixed
Parameters
$publicKey : string

Raw 32-byte Ed25519 public key

$privateKey : string|null = null

Optional raw 32-byte Ed25519 private key (seed)

fromAccountId()

Creates a KeyPair from a Stellar account ID (public key)

public static fromAccountId(string $accountId) : KeyPair

The account ID is the base32-encoded public key starting with 'G' (or 'M' for muxed accounts). Note: This creates a public-key-only keypair that cannot sign transactions.

Parameters
$accountId : string

Base32-encoded account ID (G... or M...)

Return values
KeyPair —

A keypair containing only the public key

fromBip39SeedHex()

Creates a KeyPair from a BIP-39 seed hex string using hierarchical deterministic derivation

public static fromBip39SeedHex(string $bip39SeedHex, int $index) : KeyPair

This is similar to fromMnemonic() but accepts the seed directly as a hex string rather than generating it from a mnemonic phrase. Uses SEP-0005 derivation path m/44'/148'/{index}'.

Parameters
$bip39SeedHex : string

The BIP-39 seed as a hexadecimal string

$index : int

The account index (0 for first account, 1 for second, etc.)

Tags
see
https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0005.md
Return values
KeyPair —

The derived keypair at the specified index

fromMnemonic()

Creates a KeyPair from a BIP-39 mnemonic phrase using hierarchical deterministic derivation

public static fromMnemonic(Mnemonic $mnemonic, int $index[, string|null $passphrase = '' ]) : KeyPair

This follows the SEP-0005 standard for deriving Stellar keypairs from mnemonics. The derivation path used is m/44'/148'/{index}'.

Parameters
$mnemonic : Mnemonic

The BIP-39 mnemonic phrase

$index : int

The account index (0 for first account, 1 for second, etc.)

$passphrase : string|null = ''

Optional BIP-39 passphrase (defaults to empty string)

Tags
see
https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0005.md
Return values
KeyPair —

The derived keypair at the specified index

fromPrivateKey()

Creates a KeyPair from raw 32-byte private key data

public static fromPrivateKey(string $privateKey) : KeyPair

SECURITY: The private key must be kept secure and never exposed. This method accepts the raw entropy bytes rather than an encoded seed.

Parameters
$privateKey : string

Raw 32-byte Ed25519 private key seed

Return values
KeyPair —

A complete keypair derived from the private key

fromPublicKey()

Creates a KeyPair from raw 32-byte public key data

public static fromPublicKey(string $publicKey) : KeyPair

Note: This creates a public-key-only keypair that cannot sign transactions.

Parameters
$publicKey : string

Raw 32-byte Ed25519 public key

Return values
KeyPair —

A keypair containing only the public key

fromSeed()

Creates a KeyPair from a Stellar secret seed (private key)

public static fromSeed(string $seed) : KeyPair

The seed is the base32-encoded private key starting with 'S'. This creates a complete keypair capable of signing transactions.

SECURITY: Handle seeds with extreme care. Never log, transmit unencrypted, or expose them.

Parameters
$seed : string

Base32-encoded secret seed starting with S

Return values
KeyPair —

A complete keypair with signing capabilities

getAccountId()

Returns the base32-encoded account ID (public key)

public getAccountId() : string

This is the Stellar address that starts with 'G' and can be safely shared publicly.

Return values
string —

The account ID starting with G

getHint()

Returns the signature hint (last 4 bytes of the public key)

public getHint() : string

The hint helps identify which key signed a transaction without including the full public key in the signature.

Return values
string —

The last 4 bytes of the public key

getPrivateKey()

Returns the raw 32-byte private key

public getPrivateKey() : string|null

SECURITY: This is the raw entropy of the private key. Keep it secure and never expose it. Returns null if this is a public-key-only keypair.

Return values
string|null —

The raw 32-byte private key, or null if not available

getPublicKey()

Returns the raw 32-byte public key

public getPublicKey() : string
Return values
string —

The raw 32-byte Ed25519 public key

getPublicKeyChecksum()

Returns the checksum bytes for the public key

public getPublicKeyChecksum() : string
Return values
string —

The last 2 bytes of the public key as checksum

getSecretSeed()

Returns the base32-encoded secret seed (private key)

public getSecretSeed() : string|null

SECURITY: The secret seed (S...) must be kept secure. Never log, transmit unencrypted, or expose this value. Returns null if this is a public-key-only keypair.

Return values
string|null —

The secret seed starting with S, or null if not available

getXdrSignerKey()

Converts this keypair to an XDR signer key

public getXdrSignerKey() : XdrSignerKey
Return values
XdrSignerKey —

XDR representation as a signer key

random()

Generates a new random KeyPair using cryptographically secure random bytes

public static random() : KeyPair

WARNING: For production use, ensure your environment has a secure random source. This method uses PHP's random_bytes() which should be cryptographically secure.

Tags
throws
Exception

If secure random byte generation fails

Return values
KeyPair —

A new randomly generated keypair

sign()

Signs data with the private key using Ed25519 signature algorithm

public sign(string $value) : string|null

SECURITY: This method requires the private key to be present in this keypair. The signature is generated using the Ed25519 algorithm which is required by the Stellar network.

Parameters
$value : string

The raw data to sign

Return values
string|null —

The raw signature bytes or null if signing fails (no private key or error)

signDecorated()

Signs data and returns a decorated signature with hint

public signDecorated(string $value) : XdrDecoratedSignature|null

The decorated signature includes both the signature and a hint (last 4 bytes of public key) to help identify which key signed the transaction.

SECURITY: This method requires the private key to be present in this keypair.

Parameters
$value : string

The raw data to sign

Return values
XdrDecoratedSignature|null —

The decorated signature or null if signing fails

signPayloadDecorated()

Signs a payload and returns a decorated signature with XORed hint

public signPayloadDecorated(string $signerPayload) : XdrDecoratedSignature|null

This is used for signed payload signers (SEP-0023) where the hint is XORed with the last 4 bytes of the payload for additional verification.

SECURITY: This method requires the private key to be present in this keypair.

Parameters
$signerPayload : string

The signer payload to sign

Tags
see
https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0023.md
Return values
XdrDecoratedSignature|null —

The decorated signature with XORed hint or null if signing fails

str_to_stream()

Converts a string into a stream resource

public str_to_stream(string $string) : resource

Internal utility method for stream operations.

Parameters
$string : string

The string to convert

Return values
resource —

A stream resource

verifySignature()

Verifies an Ed25519 signature against a message using this keypair's public key

public verifySignature(string $signature, string $message) : bool
Parameters
$signature : string

The signature bytes to verify

$message : string

The original message that was signed

Return values
bool —

True if the signature is valid, false otherwise

getEd25519SecretKey()

Derives the Ed25519 secret key from the seed

protected getEd25519SecretKey() : string|null

Internal method for signature operations.

Return values
string|null —

The 64-byte Ed25519 secret key, or null if no private key


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results