Custom Stellar Transactions

Prerequisites

Ensure you have a wallet created.
Signer: The signing wallet must be registered as a signer on the wallet. You can do this at wallet creation by passing signers, or afterward by adding a signer.
API Key: Ensure you have an API key with the scopes: wallets:transactions.create.

What is sending a custom transaction?

Sending a custom transaction lets you interact with any smart contract on the blockchain beyond simple transfers. Common use cases include minting free tokens, claiming rewards, or registering for allowlists—all without needing to manage private keys yourself.

Sending a contract call transaction

import { useWallet, StellarWallet } from '@crossmint/client-sdk-react-ui';

const { wallet } = useWallet();

const stellarWallet = StellarWallet.from(wallet);

const { hash, explorerLink } = await stellarWallet.sendTransaction({
    contractId: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
    method: "transfer",
    args: {
        to: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
        from: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
        amount: "1000000000000000000"
    }
});

See the React SDK reference for more details.

import { CrossmintWallets, createCrossmint, StellarWallet } from "@crossmint/wallets-sdk";

const SERVER_API_KEY = process.env.SERVER_API_KEY!;
const CROSSMINT_SIGNER_SECRET = process.env.CROSSMINT_SIGNER_SECRET!;
// Replace with your wallet address
const WALLET_ADDRESS = "YOUR_WALLET_ADDRESS";

const crossmint = createCrossmint({
    apiKey: SERVER_API_KEY,
});

const crossmintWallets = CrossmintWallets.from(crossmint);

const wallet = await crossmintWallets.getWallet(
    WALLET_ADDRESS,
    { chain: "stellar" }
);

await wallet.useSigner({ type: "server", secret: CROSSMINT_SIGNER_SECRET });

const stellarWallet = StellarWallet.from(wallet);

try {
    const { hash, explorerLink } = await stellarWallet.sendTransaction({
        contractId: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
        method: "transfer",
        args: {
            to: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
            from: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
            amount: "1000000000000000000"
        }
    });
    console.log("Transaction sent:", hash, explorerLink);
} catch (error) {
    console.error("Failed to send transaction:", error);
    throw error;
}

See the SDK reference for all parameters and return types.

import { useWallet, StellarWallet } from '@crossmint/client-sdk-react-native-ui';

const { wallet } = useWallet();

const stellarWallet = StellarWallet.from(wallet);

const { hash, explorerLink } = await stellarWallet.sendTransaction({
    contractId: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
    method: "transfer",
    args: {
        to: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
        from: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
        amount: "1000000000000000000"
    }
});

See the React Native SDK reference for more details.

The Swift SDK sends raw Stellar transactions as a base64-encoded XDR string. Build and serialize the Transaction object using the stellar-ios-mac-sdk, then pass the resulting XDR string to sendTransaction.

import CrossmintClient
import Wallet
import stellarsdk

let sdk = CrossmintSDK.shared

let wallet = try await sdk.crossmintWallets.getWallet(
    chain: StellarChain.stellar,
    recovery: StellarSigners.email("user@example.com")
)

let stellarWallet = try StellarWallet.from(wallet: wallet)

// Build a Stellar transaction using the stellar-ios-mac-sdk and serialize it to XDR.
// Replace this with your own transaction construction logic.
let stellarSDK = StellarSDK(withHorizonUrl: "https://horizon-testnet.stellar.org")
let sourceAccount = try await stellarSDK.accounts.getAccountDetails(accountId: wallet.address)
let destinationAccountId = "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J"
let paymentOperation = try PaymentOperation(
    sourceAccountId: nil,
    destinationAccountId: destinationAccountId,
    asset: Asset(type: AssetType.ASSET_TYPE_NATIVE)!,
    amount: 10.0
)
let transaction = try Transaction(
    sourceAccount: sourceAccount,
    operations: [paymentOperation],
    memo: Memo.none
)

// Serialize to base64 XDR
let transactionXDR = try transaction.encodedEnvelope()

let result = try await stellarWallet.sendTransaction(transaction: transactionXDR)
print("Transaction hash: \(result.onChainTransactionId ?? "")")

Parameters

String

required

A base64-encoded XDR envelope of the serialized Stellar transaction.

Returns

string

The on-chain transaction hash.

import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

final controller = CrossmintWalletContext.of(context).requireWalletController;
final stellarWallet = controller.createStellarWallet();

final tx = await stellarWallet.sendTransaction(
  const CrossmintStellarContractCallRequest(
    contractId: 'GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J',
    method: 'transfer',
    args: <String, Object?>{
      'to': 'GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J',
      'from': 'GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J',
      'amount': '1000000000000000000',
    },
  ),
);
print('Transaction: ${tx.id}');

See the Flutter SDK reference for more details.

Transactions must be approved by one of the wallet’s signers. The SDK handles this automatically, but with the REST API you must approve the transaction to complete it.

Create the transaction

Call the create transaction endpoint.

curl --request POST \
    --url https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-locator>/transactions \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --data '{
        "params": {
            "transaction": {
                "type": "contract-call",
                "contractId": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                "method": "transfer",
                "args": {
                    "to": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                    "from": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                    "amount": "1000000000000000000"
                }
            },
            "signer": "server:YOUR_SERVER_SIGNER_ADDRESS"
        }
    }'

// Replace with your wallet locator
const WALLET_LOCATOR = "YOUR_WALLET_LOCATOR";
const url = `https://staging.crossmint.com/api/2025-06-09/wallets/${WALLET_LOCATOR}/transactions`;

const SERVER_API_KEY = process.env.SERVER_API_KEY;
// Replace with your server signer address
const SIGNER_ADDRESS = "YOUR_SERVER_SIGNER_ADDRESS";

const payload = {
    params: {
        transaction: {
            type: "contract-call",
            contractId: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
            method: "transfer",
            args: {
                to: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                from: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                amount: "1000000000000000000"
            }
        },
        signer: `server:${SIGNER_ADDRESS}`
    }
};

const options = {
    method: 'POST',
    headers: {
        'X-API-KEY': SERVER_API_KEY,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
};

try {
    const response = await fetch(url, options);
    const data = await response.json();
    console.log(data);
} catch (error) {
    console.error(error);
}

import os
import requests

SERVER_API_KEY = os.environ["SERVER_API_KEY"]
# Replace with your wallet locator
WALLET_LOCATOR = "YOUR_WALLET_LOCATOR"
# Replace with your server signer address
SIGNER_ADDRESS = "YOUR_SERVER_SIGNER_ADDRESS"

url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{WALLET_LOCATOR}/transactions"

payload = {
    "params": {
        "transaction": {
            "type": "contract-call",
            "contractId": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
            "method": "transfer",
            "args": {
                "to": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                "from": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                "amount": "1000000000000000000"
            }
        },
        "signer": f"server:{SIGNER_ADDRESS}"
    }
}
headers = {
    "X-API-KEY": SERVER_API_KEY,
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

See the API reference for more details.

Choose your signer type

The next steps depend on which signer type you specified in the previous step.

Server Signer
Device Signer
External Wallet
Email & Phone
Passkey

Server signers derive a private key from your signer secret using HKDF-SHA256 and sign transactions locally.When using the SDK, signing and approval are handled automatically — no additional steps are needed.When using the REST API directly, you must:

Derive the signing key from your signer secret (scoped to your project, environment, and chain type). See the derive-server-signer helper for a reference implementation.
Sign the approval message returned from the transaction creation step.
Submit the signature via the approve transaction endpoint.

Crossmint recommends using the Wallets SDK for server signer flows. The SDK handles key derivation and signing automatically.

See the Server Signer guide for full configuration and setup details.

For External Wallet signers, you must manually sign the approval message and submit it via the API. The response from Step 1 includes a pending approval with a message field that must be signed exactly as returned.From the previous step’s response, extract:

id - The transaction ID (used in the next step)
approvals.pending[0].message - The hex message to sign

Sign the message using your external wallet. The message is a raw hex string and must be signed exactly as returned. Here’s an example using an EVM wallet with Viem:

import { privateKeyToAccount } from "viem/accounts";

// The message from tx.approvals.pending[0].message
const messageToSign = "<messageFromResponse>";

// Sign the message exactly as returned (raw hex)
const account = privateKeyToAccount(`0x${"<privateKey>"}`);
const signature = await account.signMessage({
    message: { raw: messageToSign },
});

Submit the approval

Skip this step if using the SDK with a server signer — the SDK handles signing and approval automatically.

Call the approve transaction endpoint with the signature from Step 2 and the transaction ID from Step 1.

curl --request POST \
    --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: <x-api-key>' \
    --data '{
        "approvals": [{
            "signer": "external-wallet:<externalWalletAddress>",
            "signature": "<signature>"
        }]
    }'

const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals';

const payload = {
    approvals: [{
        signer: "external-wallet:<externalWalletAddress>",
        signature: "<signature>"
    }]
};

const options = {
    method: 'POST',
    headers: {
        'X-API-KEY': '<x-api-key>',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
};

try {
    const response = await fetch(url, options);
    const data = await response.json();
    console.log(data);
} catch (error) {
    console.error(error);
}

import requests

url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals"

payload = {
    "approvals": [{
        "signer": "external-wallet:<externalWalletAddress>",
        "signature": "<signature>"
    }]
}
headers = {
    "X-API-KEY": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

See the API reference for more details.

Introduction

Quickstarts ⚡️

Concepts

Guides

API Reference

Prerequisites

What is sending a custom transaction?

Sending a contract call transaction

Parameters

Returns

​Prerequisites

​What is sending a custom transaction?

​Sending a contract call transaction

​Parameters

​Returns

Prerequisites

What is sending a custom transaction?

Sending a contract call transaction

Parameters

Returns