Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.privy.io/llms.txt

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

​
0. Prerequisites

This guide assumes the setup guide is complete and a Privy client instance is available.

​
1. Creating a wallet

First, create a wallet. The wallet’s id is used in future calls to sign messages and send transactions. 
begin
  wallet = client.wallets.create(
    wallet_create_params: {chain_type: :ethereum}
  )
  wallet_id = wallet.id
rescue Privy::Errors::APIStatusError => e
  # Non-2xx HTTP status codes (e.g. 400, 401, 404, 429, 5xx)
  puts(e.status)
  puts(e.message)
rescue Privy::Errors::APIConnectionError => e
  # Network-level errors raised by `net/http`
  puts(e.cause)
end
Learn more about creating wallets.
When using the PrivyClient to interact with the API, all errors raised inherit from Privy::Errors::APIError. Catch Privy::Errors::APIStatusError for non-2xx responses (with status and message available) or more specific subclasses such as RateLimitError, BadRequestError, or NotFoundError.

​
User wallets

Create a self-custodial user wallet by first creating a user, then provisioning a wallet for that user. 
begin
  user = client.users.create(
    user_create_params: {
      linked_accounts: [{type: :email, address: "[email protected]"}]
    }
  )

  wallet = client.wallets.create(
    wallet_create_params: {
      chain_type: :ethereum,
      owner: {user_id: user.id}
    }
  )
rescue Privy::Errors::APIError => e
  puts(e.message)
end
When creating a user wallet, specify the user ID as the owner of the wallet. Obtain a user ID by first creating a user before creating the wallet.Alternatively, create a user and wallet at the same time by passing wallets: to users.create.

​
2. Signing a message

Next, sign a plaintext message with the wallet using the rpc method on the wallets service. Use personal_sign for Ethereum and signMessage for Solana, and specify the wallet ID (not address) from creation. 
response = client.wallets.rpc(
  wallet_id,
  wallet_rpc_request_body: {
    method: "personal_sign",
    chain_type: "ethereum",
    params: {message: "Hello, Privy!", encoding: "utf-8"}
  }
)

# Signature is hex-encoded for Ethereum
signature = response.data.signature
Learn more about signing messages.

​
3. Sending transactions

The wallet must have funds to send a transaction. Use a testnet faucet to test transacting on a testnet (e.g. Base Sepolia) or send funds to the wallet on the network of choice.
To send a transaction from a wallet, call wallets.rpc with eth_sendTransaction for Ethereum or signAndSendTransaction for Solana. The SDK populates missing network-related values, signs the transaction, broadcasts it to the network, and returns the transaction hash. In the request, specify the wallet id from wallet creation above, as well as the caip2 chain ID for the target network. 
caip2 = "eip155:11155111" # Sepolia testnet

response = client.wallets.rpc(
  wallet_id,
  wallet_rpc_request_body: {
    method: "eth_sendTransaction",
    chain_type: "ethereum",
    caip2: caip2,
    params: {
      transaction: {
        to: recipient_address,
        value: "0x1", # 1 wei
        chain_id: 11_155_111 # Sepolia testnet
      }
    }
  }
)

transaction_hash = response.data.hash
Learn more about sending transactions.
For more control, prepare and broadcast the transaction independently, and use raw signing methods (eth_signTransaction for EVM and signTransaction for Solana) to sign the transaction with a wallet.

​
4. Creating a user

To create a user for an application, use the create method on the users service. Pass in linked accounts, custom metadata, and wallets to associate with the user. 
user = client.users.create(
  user_create_params: {
    linked_accounts: [
      {type: :custom_auth, custom_user_id: "your-subject-id"},
      {type: :email, address: "[email protected]"}
    ]
  }
)

user_id = user.id
Learn more about creating users, and see the pregenerating wallets guide for linking wallets to users before they sign in.

​
Next steps

Authorization keys

Add an extra layer of security by signing requests with authorization keys.

Policies

Restrict what wallets can do with configurable policies.

Idempotency keys

Prevent duplicate transactions with idempotency key support.

Quorum approvals

Require multiple parties to approve before sending a transaction.