0. Prerequisites
This guide assumes that you have completed the Setup guide to get a Privy client instance.1. Creating a wallet
First, we will create a wallet. You will use this wallet’sid
in future calls to sign messages and send transactions.
Learn more about creating wallets.
When using the
PrivyClient
to work with the API, all errors thrown will be instances of
privy_rs::Error
. This error type implements std::error::Error
, so you can use it with ?
to
propagate errors or your favorite error handling library such as anyhow
. You can see more
examples in the error handling section below.2. Signing a message
Next, we’ll sign a plaintext message with the wallet using chain-specific signing methods. Make sure to specify your wallet ID from creation in the input.Learn more about signing messages.
3. Sending transactions
Your wallet must have some funds in order to send a transaction. You can use a testnet
faucet to test transacting on a testnet (e.g. Base Sepolia)
or send funds to the wallet on the network of your choice.
id
from your wallet creation above, as well as the caip2
chain ID for the network you want to transact on.
Learn more about sending transactions.
If you’re interested in more control, you can prepare and broadcast the transaction yourself, and
simply use raw signing methods to sign the transaction with a wallet.
4. Creating a user
To create a user for your application, you can use thecreate
method, passing in linked accounts, custom metadata, and wallets that should be associated with said user.
Learn more about creating
users, and look at our pregenerating wallets guide
for linking wallets to your users before they even sign in.
5. Error handling
In the examples above we use?
to propagate errors, however the Rust SDK provides comprehensive error handling through multiple specialized error types. All error types implement std::error::Error
, allowing seamless integration with Rust’s error handling ecosystem.
Error types
The SDK provides the following main error categories:PrivyApiError
The core generated client error type that represents all possible API communication failures:Error Variant | Description | When It Occurs |
---|---|---|
InvalidRequest | Request doesn’t conform to API requirements | Missing required fields, invalid data formats |
CommunicationError | Network or connection issues | Network timeouts, DNS failures, connection drops |
InvalidUpgrade | Connection upgrade failed | WebSocket or HTTP/2 upgrade errors |
ErrorResponse | Documented API error response | Authentication failures, insufficient permissions |
ResponseBodyError | Failed to read response body | Corrupted response data |
InvalidResponsePayload | Response deserialization failed | Unexpected response format |
UnexpectedResponse | Undocumented response code | New API responses not yet supported |
Custom | Consumer-defined hook error | Custom validation or processing failures |
PrivyCreateError
Client initialization errors that occur when creating aPrivyClient
instance:
Error Variant | Description | When It Occurs |
---|---|---|
InvalidHeaderValue | Invalid HTTP header value provided | Malformed app credentials |
Client | HTTP client creation failed | Network configuration issues |
PrivySignedApiError
Errors for operations requiring cryptographic signatures (authorization keys):Error Variant | Description | When It Occurs |
---|---|---|
Api | Privy API returned an error response | Authentication failures, rate limits |
SignatureGeneration | Failed to generate request signature | Invalid private key, signing errors |
PrivyExportError
Wallet export operation errors:Error Variant | Description | When It Occurs |
---|---|---|
Api | Privy API returned an error response | Export permissions, wallet access |
SignatureGeneration | Failed to generate request signature | Invalid authorization key |
Key | Decryption or key handling failed | Invalid encryption key, corrupted data |
CryptoError
General cryptographic operation errors:Error Variant | Description | When It Occurs |
---|---|---|
Signing | Digital signature operation failed | Invalid key, signature algorithm issues |
Key | Key handling operation failed | Key parsing, loading, or format errors |
KeyError
Cryptographic key management errors:Error Variant | Description | When It Occurs |
---|---|---|
Io | File I/O error reading key | Missing key file, permission denied |
InvalidFormat | Key data is malformed | Invalid PEM/DER format, corrupted data |
HpkeDecryption | HPKE decryption failed | Wrong decryption key, corrupted payload |
Other | Unknown error occurred | Unexpected system errors |
SigningError
Digital signature creation errors:Error Variant | Description | When It Occurs |
---|---|---|
Key | Invalid signing key | Wrong key type, corrupted key data |
Signature | Cryptographic signing failed | Algorithm errors, hardware issues |
Other | Unknown signing error | Unexpected cryptographic errors |
SignatureGenerationError
Authorization signature generation errors:Error Variant | Description | When It Occurs |
---|---|---|
Serialization | Request serialization failed | Invalid request data structure |
Signing | Signing process failed | Key errors, cryptographic failures |
Basic error handling
Advanced error handling
Integration with error handling libraries
The SDK works seamlessly with popular Rust error handling libraries:We also implement logging via the tracing crate, which is a
popular and well-supported logging facade for Rust.
Next steps & advanced topics
- For an additional layer of security, you can choose to sign your requests with authorization keys.
- To restrict what wallets can do, you can set up policies.
- To prevent double sending the same transaction, take a look at our support for idempotency keys.
- If you want to require multiple parties to sign off before sending a transaction for a wallet, you can accomplish this through the use of quorum approvals.