Once you have created a wallet with a user signer, you can transact on that wallet with a valid user JWT. To do so, your application will

  • Request a time-bound session key from the user signer API using the user’s JWT.
  • Request a transaction from the Wallet API, signed with the user session key.

Get session key

The first step to transact with a wallet via a user signer is to request a session key via the /v1/signers/authenticate endpoint. This time-bound session key will be used to sign the request before it is submitted to the Privy Wallet API. The expiration time of this session key is returned in the response.

The /v1/signers/authenticate endpoint integrates directly with the JWT-based authentication settings configured in the Privy dashboard. In particular, the JWT is verified according to the registered JWKS.json endpoint. This endpoint uniquely identifies users based on the subject ID (the sub claim) within the JWT and verifies the JWT is authorized to transact on the wallet.

Request

A request body to /v1/signers/authenticate contains the following parameters.

user_jwt
string
required

The user’s JWT, to be used to authenticate the user.

encryption_type
'HPKE
required

The encryption type for the authentication response. Currently only supports HPKE.

recipient_public_key
string
required

Base64-encoded public key of the recipient who will decrypt the session key. This key must be generated securely and kept confidential.

Response

A successful response will contain the following fields.

encrypted_authorization_key
object
expires_at
number

The expiration time of the authorization key in seconds since the epoch.

wallets
object[]

The wallets that the signer has access to.

Example

For example, your application may make a request to the /v1/signers/authenticate endpoint with the following parameters.

{
  user_jwt: <user-jwt>,
  encryption_type: 'HPKE',
  recipient_public_key: <ephemeral-public-key>
}

A successful response will look like the following.

{
  "encrypted_authorization_key": {
    "encryption_type": "HPKE",
    "encapsulated_key": "<encapsulated-key",
    "ciphertext": "<ciphertext>",
  },
   "expires_at": 1715270400,
   "wallets": [
      {
        "id": "<wallet-id>",
        "chain_type": "ethereum",
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      },
   ]
}

Then, decrypt the ciphertext with the recipient_public_key specified in the request to get the session key. Use this session key to generate an authorization signature for the transaction request.

Request transaction

With this session key, your application can request a transaction via the Wallet API.

To request a transaction:

As an example, your application may use the /v1/wallets/[wallet_id]/rpc endpoint to submit a transaction from the wallet with the following parameters.

{
  method: "eth_sendTransaction",
  caip2: "eip155:11155111",
  chain_type: "ethereum",
  params: {
    transaction: {
      to: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      value: 5000000000
    }
  }
}

The /v1/wallets/[wallet_id]/rpc returns a transaction ID that can be used to monitor the status of this transaction.