Delegated Keys

Allow delegated keys to obtain partial or full control of the wallet

Crossmint wallets can be controlled by more than one signer. This feature is useful when you have wallets that require flexible custodial architectures, such as:

• Company treasury wallets managed by multiple employees
• AI agent wallets, where the agent owner needs a key, and the agent itself needs another one
• Neobanks and other financial applications where the user is self-custodial but opts into allowing the bank to pull funds (e.g. for debit card)

A key characteristic in delegated signers is that they can be scoped to limit the permissions they have over the wallet, for example with spend or asset classes restrictions.

A Signer refers to any private/public key pair that can cryptographically sign messages. This includes crypto wallets, passkeys, hardware security modules (HSMs), and other signing mechanisms that can prove ownership or authorization through digital signatures.

Key Characteristics

• 🔐 Enabled Delegated Access Securely: Allow third parties to control a wallet, with scoped permissions
• ⚡ Autonomous Operations: Enable AI agents to execute independently over a wallet
• 🎯 Granular Control: Set permissions and expiration dates for each delegated keys capabilities
• 🔑 Hybrid Custody: Keep a wallet non custodial for currencies, but allow your app’s backend to manage its non-regulated assets (such as utility tokens or NFTs)

How Delegated Signers Work

1. Enroll: The admin signer for the wallet sends a transaction to add a delegated signer to the wallet, optionally specifying a set of restrictions
2. Transact: The delegated signer can now perform transactions
3. Unenroll: The admin signer can later revoke access to any delegated signer

Technical Implementation

In this quickstart, we propose a scenario where there’s a smart wallet that is owned by two keys: an admin key held by the wallet owner, and a delegated key given to an AI agent, with a restricted set of permissions.

Integration Steps

1

Create and Configure a Crossmint Project

To get started, create a developer account in the Crossmint Staging Console. Open that link, sign in, and accept the dialog to continue.

Crossmint offers two consoles: staging, for development and testing, and production.

2

Get an API Key

Once you log in to the console, the next step is to create an API key.

• Navigate to project Integrate > API Keys, and click the “Create new key” button in the “Server-side keys” section
• Under the Wallets API category, select the scopes wallets.create, wallets.read, wallets:signatures.create, wallets:transactions.create, wallets:transactions.read, and wallets:transactions.sign
• Click “Create server key” to save the key for the next step

For all requests to the Crossmint API, add the following headers:

headers

{
    "X-API-KEY": "your_server_api_key",
    "Content-Type": "application/json",
}

Create a Delegated Key and Send a Transaction

• EVM
• Solana

1

Create a Smart Wallet

First, we create a Smart Wallet, controlled by the developer’s key, which will be called the admin signer.

You can use a webauthn passkey as admin signer, an existing ethereum address, or generate an ethereum wallet in code.

In this quickstart we will generate the admin signer key in code:

generateKey.ts

import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
const privateKey = generatePrivateKey();
const adminSigner = privateKeyToAccount(privateKey);
console.log(adminSigner.address);
// > "0x234"

This address is not the wallet you’ll put funds in. It’s just a key that will be used to control the smart wallet, which we create below.

Save the private key for the admin signer securely, you’ll use it later to approve a transaction.

Now, we are going to create a Smart Wallet and set its owner to be the admin key we just created.

To do so, we call the Create wallet endpoint with the following body:

body

{
   type: "evm-smart-wallet",
   config: {
        adminSigner: { 
            type: "evm-keypair", 
            address: "0x234" 
        }
   }
}

With this, we have a smart wallet created, and it can be controlled by the admin (agent owner), 0x234.

2

Create a Key for the Agent

As a next step, we want to create a separate key that will be held by our agent. This key will be able to send transactions on behalf of the smart wallet, but will have some restrictions attached.

For this tutorial, we will generate the agent key following the same steps as the admin key:

generateKey.ts

import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";

const agentKey = generatePrivateKey();
const agentSigner = privateKeyToAccount(agentKey);
console.log(agentSigner.address);
// > "0x569"

Then we should store the private key somewhere safe that the agent can access. For example, as an environment variable in the server that the agent is running on.

And now we register the address above as a delegated signer for the smart wallet, using the address locator returned when we created the wallet:

request

POST https://staging.crossmint.com/api/2022-06-09/wallets/0xdeadbeef/signers

body: {
    signer: "evm-keypair:0x0x569
    chain: "base",
    expiresAt: 1735845180080  // timestamp in ms since Unix epoch

    // Additional signer permissions can be set as per ERC-7715
    // permissions: {
    //     type: "rate-limit",
    //     data: {
    //         count: 100,     // Allow 100 calls
    //         interval: 3600  // Within each 1-hour period (3600 seconds)
    //     }
    // },
}

3

Approve Registration of Agent Signer with the Admin Key

The admin signer needs to approve the registration of the agent’s key as a delegated signer, by signing the message from the response, i.e. 0xme55ageTo5ign - note that the response above is “awaiting-approval”.

approveDelegatedSigner.ts

const signature = adminSigner.signMessage({
    message: { raw: "0xme55ageTo5ign" },
});
console.log(signature);
// > 0xa22cb4650000000000000000000000000000000000000013

We now need to submit that signed message using the signature approval endpoint, POST https://staging.crossmint.com/api/2022-06-09/wallets/0xdeadbeef/signatures/1bc61c9d-0929-4782-a21c-177acda93a2d/approvals and pass the following body:

body

{
    approvals: [
        {
            signer: "evm-keypair:0x234",
            signature: "0xa22cb4650000000000000000000000000000000000000013"
        }
    ]
}

And with this, the agent key now has delegated access to the smart wallet 🎉

4

Send a Transaction from the Agent

Now that the agent’s key is approved, it can create transactions on the developer’s behalf, as long as transactions respect the defined permissions.

Here we are going to make a USDC transfer. The first step is to prepare the transaction:

prepareTransaction.ts

import { encodeFunctionData, parseUnits } from 'viem';

// USDC contract address on Base
const usdcAddress = '0x036CbD53842c5426634e7929541eC2318f3dCF7e';

// Recipient address and amount to send (5 USDC)
const recipient = '0xRecipientAddress'; // Replace with the recipient's address
const amount = parseUnits('5', 6);      // 5 USDC (6 decimals)

// Encode the data for the transfer function
const data = encodeFunctionData({
    abi: [
        {
            "constant": false,
            "inputs": [
                { "name": "recipient", "type": "address" },
                { "name": "amount", "type": "uint256" }
            ],
            "name": "transfer",
            "outputs": [{ "name": "", "type": "bool" }],
            "type": "function"
        }
    ],
    functionName: 'transfer',
    args: [recipient, amount]
});

console.log('Transaction Data:', data);

Now we will use the transaction data generated and the Create Transaction API to submit a new transaction for the smart wallet with the following body:

body

// Send 5 USDC to another agent
{
   params: {
      calls: [{
      		to: "0x036CbD53842c5426634e7929541eC2318f3dCF7e", // USDC address from above
      		data: "...", // data output from above
      		value: "0"
      }],
      // use the session key signer
      signer: "evm-keypair:0x569",
      chain: "base"
   }
}

5

Approve Transaction

The agent, via its delegated key, signs the transaction message to approve it. Then, it will be broadcasted onchain.

Like before, the message to sign is “awaiting-approval” in the previous response.

approveTransaction.ts

const signature = agentSigner.signMessage({
    message: { raw: "0xn3Wme55ageTo5ign" },
});
console.log(signature);
// > 0xa22cb4650000000000000000000000000000000000000013

To submit the transaction, use the Transaction Approval API to pass the signature in the body, the transactionId from Step 4 in the route’s path, and the wallet’s locator, 0xdeadbeef:

body

{
    approvals: [
        {
            signer: "evm-keypair:0x569",
            signature: "0xa22cb4650000000000000000000000000000000000000013"
        }
    ]
}

With this, our agent has already submitted its first transaction! 🕺

6

(Bonus) Check transactions for a wallet

The agent developer can easily fetch transactions executed by their wallet, as well as filter the responses based on signer to audit transactions by specific agents.

request

GET https://staging.crossmint.com/api/2022-06-09/wallets/0xdeadbeef/transactions

1

Create a Smart Wallet

First, we create a Smart Wallet, controlled by the developer’s key, which will be called the admin signer.

You can use a webauthn passkey as admin signer, an existing ethereum address, or generate an ethereum wallet in code.

In this quickstart we will generate the admin signer key in code:

generateKey.ts

import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
const privateKey = generatePrivateKey();
const adminSigner = privateKeyToAccount(privateKey);
console.log(adminSigner.address);
// > "0x234"

This address is not the wallet you’ll put funds in. It’s just a key that will be used to control the smart wallet, which we create below.

Save the private key for the admin signer securely, you’ll use it later to approve a transaction.

Now, we are going to create a Smart Wallet and set its owner to be the admin key we just created.

To do so, we call the Create wallet endpoint with the following body:

body

{
   type: "evm-smart-wallet",
   config: {
        adminSigner: { 
            type: "evm-keypair", 
            address: "0x234" 
        }
   }
}

With this, we have a smart wallet created, and it can be controlled by the admin (agent owner), 0x234.

2

Create a Key for the Agent

As a next step, we want to create a separate key that will be held by our agent. This key will be able to send transactions on behalf of the smart wallet, but will have some restrictions attached.

For this tutorial, we will generate the agent key following the same steps as the admin key:

generateKey.ts

import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";

const agentKey = generatePrivateKey();
const agentSigner = privateKeyToAccount(agentKey);
console.log(agentSigner.address);
// > "0x569"

Then we should store the private key somewhere safe that the agent can access. For example, as an environment variable in the server that the agent is running on.

And now we register the address above as a delegated signer for the smart wallet, using the address locator returned when we created the wallet:

request

POST https://staging.crossmint.com/api/2022-06-09/wallets/0xdeadbeef/signers

body: {
    signer: "evm-keypair:0x0x569
    chain: "base",
    expiresAt: 1735845180080  // timestamp in ms since Unix epoch

    // Additional signer permissions can be set as per ERC-7715
    // permissions: {
    //     type: "rate-limit",
    //     data: {
    //         count: 100,     // Allow 100 calls
    //         interval: 3600  // Within each 1-hour period (3600 seconds)
    //     }
    // },
}

3

Approve Registration of Agent Signer with the Admin Key

The admin signer needs to approve the registration of the agent’s key as a delegated signer, by signing the message from the response, i.e. 0xme55ageTo5ign - note that the response above is “awaiting-approval”.

approveDelegatedSigner.ts

const signature = adminSigner.signMessage({
    message: { raw: "0xme55ageTo5ign" },
});
console.log(signature);
// > 0xa22cb4650000000000000000000000000000000000000013

We now need to submit that signed message using the signature approval endpoint, POST https://staging.crossmint.com/api/2022-06-09/wallets/0xdeadbeef/signatures/1bc61c9d-0929-4782-a21c-177acda93a2d/approvals and pass the following body:

body

{
    approvals: [
        {
            signer: "evm-keypair:0x234",
            signature: "0xa22cb4650000000000000000000000000000000000000013"
        }
    ]
}

And with this, the agent key now has delegated access to the smart wallet 🎉

4

Send a Transaction from the Agent

Now that the agent’s key is approved, it can create transactions on the developer’s behalf, as long as transactions respect the defined permissions.

Here we are going to make a USDC transfer. The first step is to prepare the transaction:

prepareTransaction.ts

import { encodeFunctionData, parseUnits } from 'viem';

// USDC contract address on Base
const usdcAddress = '0x036CbD53842c5426634e7929541eC2318f3dCF7e';

// Recipient address and amount to send (5 USDC)
const recipient = '0xRecipientAddress'; // Replace with the recipient's address
const amount = parseUnits('5', 6);      // 5 USDC (6 decimals)

// Encode the data for the transfer function
const data = encodeFunctionData({
    abi: [
        {
            "constant": false,
            "inputs": [
                { "name": "recipient", "type": "address" },
                { "name": "amount", "type": "uint256" }
            ],
            "name": "transfer",
            "outputs": [{ "name": "", "type": "bool" }],
            "type": "function"
        }
    ],
    functionName: 'transfer',
    args: [recipient, amount]
});

console.log('Transaction Data:', data);

Now we will use the transaction data generated and the Create Transaction API to submit a new transaction for the smart wallet with the following body:

body

// Send 5 USDC to another agent
{
   params: {
      calls: [{
      		to: "0x036CbD53842c5426634e7929541eC2318f3dCF7e", // USDC address from above
      		data: "...", // data output from above
      		value: "0"
      }],
      // use the session key signer
      signer: "evm-keypair:0x569",
      chain: "base"
   }
}

5

Approve Transaction

The agent, via its delegated key, signs the transaction message to approve it. Then, it will be broadcasted onchain.

Like before, the message to sign is “awaiting-approval” in the previous response.

approveTransaction.ts

const signature = agentSigner.signMessage({
    message: { raw: "0xn3Wme55ageTo5ign" },
});
console.log(signature);
// > 0xa22cb4650000000000000000000000000000000000000013

To submit the transaction, use the Transaction Approval API to pass the signature in the body, the transactionId from Step 4 in the route’s path, and the wallet’s locator, 0xdeadbeef:

body

{
    approvals: [
        {
            signer: "evm-keypair:0x569",
            signature: "0xa22cb4650000000000000000000000000000000000000013"
        }
    ]
}

With this, our agent has already submitted its first transaction! 🕺

6

(Bonus) Check transactions for a wallet

The agent developer can easily fetch transactions executed by their wallet, as well as filter the responses based on signer to audit transactions by specific agents.

request

GET https://staging.crossmint.com/api/2022-06-09/wallets/0xdeadbeef/transactions

1

Create a Smart Wallet

First, we create a Smart Wallet, controlled by the developer’s key, which will be called the admin signer.

generateKey.ts

import { Keypair } from "@solana/web3.js";
import bs58 from 'bs58';

const adminSigner = Keypair.generate();
console.log("Admin signer address: ", adminSigner.publicKey.toBase58());
console.log("Admin signer secret key: ", bs58.encode(adminSigner.secretKey));
// > "Admin signer address: <admin-signer-address>"

This address is not the wallet you’ll put funds in. It’s just a key that will be used to control the smart wallet, which we create below.

Save the private key for the admin signer securely.

Now, we are going to create a Smart Wallet and set its owner to be the admin key we just created.

To do so, we call the Create Wallet endpoint with the following body:

body

POST https://staging.crossmint.com/api/2022-06-09/wallets

{
   type: "solana-smart-wallet",
   config: {
        adminSigner: { 
            type: "solana-keypair", 
            address: "<admin-signer-address>" 
        }
   }
}

With this, we have a smart wallet created, and it can be controlled by the admin (agent owner), <admin-signer-address>.

2

Create a Key for the Agent

As a next step, we want to create a separate key that will be held by our agent. This key will be able to send transactions on behalf of the smart wallet, but will have some restrictions attached.

By default, delegated signers cannot perform administrative operations on the wallet. This means they cannot:

• Add or remove other signers
• Change wallet configuration
• Upgrade the wallet implementation
• Transfer wallet ownership

Only the admin signer (wallet owner) has these privileges. This security measure ensures that delegated keys can only perform the specific operations they’ve been authorized for.

For this tutorial, we will generate the agent key following the same steps as the admin key:

generateKey.ts

import { Keypair } from "@solana/web3.js";
import bs58 from 'bs58';

const agentSigner = Keypair.generate();
console.log("Agent signer address: ", agentSigner.publicKey.toBase58());
console.log("Agent signer secret key: ", bs58.encode(agentSigner.secretKey));
// > "Agent signer address: <agent-signer-address>"

Then we should store the private key somewhere safe that the agent can access. For example, as an environment variable in the server that the agent is running on.

Solana wallets support a maximum of 10 delegated signers due to blockchain transaction size limits. When planning your application, ensure you manage your signer slots efficiently. If you need to add a new signer when at capacity, consider removing an unused signer first.

And now we register the agent signer address as a Delegated Signer for the smart wallet, using the address locator returned when we created the wallet:

request

POST https://staging.crossmint.com/api/2022-06-09/wallets/<wallet-locator>/signers

body: {
    "signer": "solana-keypair:<agent-signer-address>"
}

Solana transactions expire after 150 blocks (approximately 1-2 minutes) so you should try and send the approval before the transaction expires.

3

Approve Registration of Agent Signer with the Admin Key

The admin signer needs to approve the registration of the agent’s key as a delegated signer, by signing the transaction from the response - note the transaction’s status above is “awaiting-approval”.

approveDelegatedSigner.ts

import bs58 from 'bs58';
import nacl from 'tweetnacl';

// From the signer response above in step 2
const message = response.transaction.approvals.pending[0].message;
const secretKey = "<admin-signer-secret-key>";

// Convert both message and secretKey from base58 to Uint8Array
const messageBytes = bs58.decode(message);
const secretKeyBytes = bs58.decode(secretKey);

const signature = bs58.encode(nacl.sign.detached(messageBytes, secretKeyBytes));
console.log("Signature:", signature);

We now need to submit that signed message using the Approve Transaction endpoint. In the route’s path include the wallet’s address and the transaction’s id, and pass the following body:

body

{
    approvals: [
        {
            signer: "solana-keypair:<admin-signer-address>",
            signature: "<signature>"
        }
    ]
}

Once this transaction is successfully broadcasted on-chain, the agent key will have delegated access to the smart wallet 🎉

4

Check the Transaction Status

The delegated signer will become usable only after the transaction is confirmed on-chain. You can check the status by retrieving the signer details or by checking the transaction status using the transaction ID returned in the response.

To check the status of the transaction, use the Get Transaction endpoint. In the route’s path include the wallet’s address and the transaction’s id:

request

GET https://staging.crossmint.com/api/2022-06-09/wallets/<wallet-locator>/transactions/<transaction-id>

5

Send a Transaction from the Agent

Now that the agent’s key is approved, it can create transactions on the developer’s behalf but it won’t be allowed to modify the wallet configuration or approve new signers.

Here we are going to make a USDC transfer. The first step is to prepare the transaction:

prepareTransaction.ts

import { TransactionMessage, PublicKey, VersionedTransaction, Connection } from "@solana/web3.js";
import {
    createTransferInstruction,
    getAssociatedTokenAddress,
    TOKEN_PROGRAM_ID,
    createAssociatedTokenAccountInstruction,
    ASSOCIATED_TOKEN_PROGRAM_ID,
} from "@solana/spl-token";
import bs58 from "bs58";

const connection = new Connection("https://api.devnet.solana.com", "confirmed");

const USDC_MINT = new PublicKey("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU"); // USDC Mint Address on Solana Devnet
const senderAddress = new PublicKey("<wallet-address>");
const recipientAddress = new PublicKey("<recipient-address>");
const amount = 1; // 1 USDC

async function createUSDCTransferTransaction(senderAddress, recipientAddress, amount) {
    // No need to create new PublicKey instances since we already did above
    const senderPublicKey = senderAddress;
    const recipientPublicKey = recipientAddress;

    const senderTokenAccount = await getAssociatedTokenAddress(USDC_MINT, senderPublicKey, true);
    const recipientTokenAccount = await getAssociatedTokenAddress(USDC_MINT, recipientPublicKey, true);

    // Amount needs to be converted to base units (multiply by 10^6 for USDC)
    const amountInBaseUnits = amount * 1_000_000;

    // Create new transaction
    const instructions = [];
    const recipientAccountInfo = await connection.getAccountInfo(recipientTokenAccount);
    if (!recipientAccountInfo) {
        instructions.push(
            createAssociatedTokenAccountInstruction(
                senderPublicKey,
                recipientTokenAccount,
                recipientPublicKey,
                USDC_MINT,
                TOKEN_PROGRAM_ID,
                ASSOCIATED_TOKEN_PROGRAM_ID
            )
        );
    }

    // Add the transfer instruction
    instructions.push(
        createTransferInstruction(
            senderTokenAccount,
            recipientTokenAccount,
            senderPublicKey,
            amountInBaseUnits,
            [],
            TOKEN_PROGRAM_ID
        )
    );

    const message = new TransactionMessage({
        instructions,
        recentBlockhash: "11111111111111111111111111111111",
        payerKey: new PublicKey("11111111111111111111111111111112"),
    }).compileToV0Message();

    const transaction = new VersionedTransaction(message);

    // Serialize and encode transaction
    return bs58.encode(transaction.serialize());
}

const base58Transaction = await createUSDCTransferTransaction(senderAddress, recipientAddress, amount);
console.log("Base58 encoded transaction:", base58Transaction);

Now we will use the transaction data generated and the Create Transaction API to submit a new transaction for the smart wallet with the following body:

body

// Send 1 USDC to another agent
{
   params: {
      transaction: "<base58-transaction-data>",
      signer: "solana-keypair:<agent-signer-address>",
    }
}

6

Approve Transaction

The agent, via its delegated key, signs the transaction message to approve it. Then, it will be broadcasted on-chain.

Like before, the message to sign is “awaiting-approval” in the previous response.

approveTransaction.ts

import bs58 from 'bs58';
import nacl from 'tweetnacl';

// From the transaction response above
const message = response.approvals.pending[0].message;
const secretKey = "<agent-signer-secret-key>";

// Convert both message and secretKey from base58 to Uint8Array
const messageBytes = bs58.decode(message);
const secretKeyBytes = bs58.decode(secretKey);

const signature = bs58.encode(nacl.sign.detached(messageBytes, secretKeyBytes));
console.log("Signature:", signature);

To submit the transaction, use the Approve Transaction API to pass the signature in the body, the transactionId from Step 4 in the route’s path, and the wallet’s locator:

body

{
    approvals: [
        {
            signer: "solana-keypair:<agent-signer-address>",
            signature: "<signature>"
        }
    ]
}

With this, our agent has already submitted its first transaction! 🕺

7

(Bonus) Check transactions for a wallet

The agent developer can easily fetch transactions executed by their wallet, as well as filter the responses based on signer to audit transactions by specific agents.

request

GET https://staging.crossmint.com/api/2022-06-09/wallets/<wallet-locator>/transactions/<transaction-id>

🎉 Advanced: Permissions System

Crossmint offers a comprehensive permissions system for delegated keys, allowing you to set precise boundaries on what actions delegated signers can perform.

EVM Smart Wallets

For EVM smart wallets, the permissions system is fully available and supports various restriction types including:

• Rate limiting (number of transactions per time period)
• Asset type restrictions (e.g., only NFTs, only specific tokens)
• Value limits (maximum transaction amounts)
• Contract address allowlists

Learn more about the complete set of options in the EVM Delegated Keys Permissions section.

Solana Smart Wallets

For Solana smart wallets, an advanced permissions system is coming soon. Currently, delegated signers have basic transaction capabilities but cannot perform administrative operations on the wallet.

Stay tuned for updates as we expand the permissions system for Solana wallets in upcoming releases. The upcoming permissions system will include token-specific restrictions, allowing you to limit which tokens a delegated signer can interact with.