Getting Started
Controller implements a standard StarkNet account interface and can be seamlessly integrated into your application like any other wallet.
Quick Start
The fastest way to get started is to install the controller package and connect to Cartridge:
import Controller from "@cartridge/controller";
const controller = new Controller({});
const account = await controller.connect();
// You're ready to execute transactions!
Installation
npm install @cartridge/controller starknet
Basic Usage
Here's a simple example of how to initialize and use the controller:
Without session policies
import Controller from "@cartridge/controller";
const controller = new Controller();
// All transactions will require manual approval
With session policies
Pass session policies to the Controller constructor to enable gasless transactions and pre-approved transactions.
import Controller from "@cartridge/controller";
import { SessionPolicies } from "@cartridge/controller";
const policies: SessionPolicies = {
contracts: {
// Your game contract
"0x1234...": {
name: "My Game Contract",
methods: [
{ name: "move_player", entrypoint: "move_player" },
{ name: "attack", entrypoint: "attack" },
],
},
},
};
const controller = new Controller({ policies });
// `move_player` and `attack` transactions will not require approval
With custom configuration
The Controller ships with sensible defaults for chain RPCs, but you can override them if needed.
import Controller from "@cartridge/controller";
import { constants } from "starknet";
const controller = new Controller({
// Optional chain configuration
chains: [
{ rpcUrl: "https://api.cartridge.gg/x/starknet/sepolia" },
{ rpcUrl: "https://api.cartridge.gg/x/starknet/mainnet" },
],
defaultChainId: constants.StarknetChainId.SN_SEPOLIA,
});
Session Connector
The SessionConnector
provides direct session management capabilities, allowing for more granular control over session handling:
import { constants } from "starknet";
import SessionConnector from "@cartridge/connector/session";
import { SessionPolicies } from "@cartridge/controller";
const policies: SessionPolicies = {
// Define session policies here
};
const sessionConnector = new SessionConnector({
policies,
rpc: "https://api.cartridge.gg/x/starknet/sepolia",
chainId: constants.StarknetChainId.SN_SEPOLIA,
redirectUrl: typeof window !== "undefined" ? window.location.origin : "",
// Optional: specify keychain URL for custom deployments
keychainUrl: "https://x.cartridge.gg",
});
The SessionConnector is ideal for applications that need:
- Direct control over session lifecycle
- Custom session management flows
- Integration with existing authentication systems
Starknet React Integration
This example shows how to integrate the ControllerConnector and SessionConnector with Starknet React.
import React from "react";
import { constants } from "starknet";
import { sepolia, mainnet } from "@starknet-react/chains";
import { StarknetConfig, jsonRpcProvider, cartridge } from "@starknet-react/core";
import ControllerConnector from "@cartridge/connector/controller";
import SessionConnector from "@cartridge/connector/session";
import { SessionPolicies } from "@cartridge/controller";
const policies: SessionPolicies = {
// Define session policies here
};
// Create the controller and session connectors
const controller = new ControllerConnector({
policies,
});
const session = new SessionConnector({
policies,
rpc: "https://api.cartridge.gg/x/starknet/sepolia",
chainId: constants.StarknetChainId.SN_SEPOLIA,
redirectUrl: typeof window !== "undefined" ? window.location.origin : ""
});
// Configure the JSON RPC provider
const provider = jsonRpcProvider({
rpc: (chain) => {
switch (chain) {
case mainnet:
return { nodeUrl: "https://api.cartridge.gg/x/starknet/mainnet" };
case sepolia:
default:
return { nodeUrl: "https://api.cartridge.gg/x/starknet/sepolia" };
}
},
});
// Create the Starknet provider with the controller and session connectors
export function StarknetProvider({ children }: { children: React.ReactNode }) {
return (
<StarknetConfig
defaultChainId={sepolia.id}
chains={[mainnet, sepolia]}
provider={provider}
connectors={[controller, session]}
explorer={cartridge}
>
{children}
</StarknetConfig>
);
}
Wallet Standard Integration
The ControllerConnector supports the get-starknet wallet standard, a higher-level interface than StarknetWindowObject
which enables integration with libraries like starknet-react
and solid.js
.
Using asWalletStandard()
You can use the ControllerConnector to cast Controller
to the wallet-standard compatible WalletWithStarknetFeatures
interface:
import { ControllerConnector } from "@cartridge/connector";
import type { WalletWithStarknetFeatures } from "@starknet-io/get-starknet-wallet-standard/features";
const controller: WalletWithStarknetFeatures = (new ControllerConnector()).asWalletStandard();
// Now compatible with any library that expects WalletWithStarknetFeatures
Compatibility Guide
The following common dependencies are compatible with the latest version of Cartridge Controller (v0.10.3):
"@cartridge/arcade": "0.0.2"
"@cartridge/connector": "0.10.3"
"@cartridge/controller": "0.10.3"
"@cartridge/presets": "0.5.4"
"@dojoengine/core": "^1.7.0"
"@dojoengine/predeployed-connector": "1.7.0-preview.3"
"@dojoengine/sdk": "^1.7.2"
"@dojoengine/torii-client": "1.7.0-preview.3"
"@dojoengine/torii-wasm": "^1.7.2"
"@dojoengine/utils": "1.7.0-preview.3"
"@starknet-io/types-js": "^0.8.4"
"@starknet-react/chains": "^5.0.1"
"@starknet-react/core": "^5.0.1"
"@tailwindcss/vite": "^4.1.4"
"@types/node": "^22.13.1"
"@types/react": "^19.1.0"
"@types/react-dom": "^19.1.0"
"bignumber.js": "^9.3.0"
"lucide-react": "^0.523.0"
"prettier": "^3.6.1"
"prettier-plugin-tailwindcss": "^0.6.13"
"react": "^19.1.0"
"react-dom": "^19.1.0"
"recharts": "^3.1.0"
"sonner": "^2.0.5"
"starknet": "^8.1.2"
"starknetkit": "^v2.12.1"
"tailwindcss": "^4.1.4"
"typescript": "^5.8.3"
"vite": "^6.3.3"
"vite-plugin-wasm": "^3.4.1"
"zustand": "^5.0.3"
Migration Notes for v0.10.0
StarkNet v8 Breaking Changes
If you're using WalletAccount
directly in your application, you'll need to update the constructor call:
// Before (v0.9.x)
const account = new WalletAccount(provider, address, signer);
// After (v0.10.0)
const account = new WalletAccount({
nodeUrl: provider,
address: address,
signer: signer
});
Ethereum Wallet Integration Changes
The MetaMask SDK has been removed in favor of the EIP-6963 standard. If your application relied on MetaMask SDK-specific features:
- Wallet detection now uses EIP-6963 standard wallet detection
- All Ethereum wallets are now handled through a shared base class
- This change improves bundle size and wallet compatibility
Lodash Removal
The lodash dependency has been completely removed. If you were importing lodash utilities from this package, you'll need to replace them with custom utilities or install lodash separately in your application.
Development Workflow
If you're contributing to the Cartridge Controller or running the examples locally, you have two development modes available:
Local Development Mode
pnpm dev
This runs all services locally with local API endpoints, perfect for offline development and testing changes to the controller itself.
Production API Testing Mode
pnpm dev:live
This hybrid mode runs the keychain and examples locally while connecting to production APIs. This is useful for:
- Testing your application against production data
- Debugging issues that only occur with production configurations
- Validating your integration before deployment
The dev:live
mode provides production RPC endpoints, Auth0, Stripe, and Turnkey configurations while keeping the keychain frame at localhost:3001
and your application at localhost:3002
.
Examples
For more detailed examples of how to use Cartridge Controller in different environments, check out our integration guides:
-
- Integration with
starknet-react
- Hooks and components
- State management
- Integration with
-
- Svelte stores and reactivity
- Component lifecycle
- Event handling
-
- Native integration
- Error handling
- Async operations
Each guide provides comprehensive examples and best practices for integrating Cartridge Controller in your preferred environment.
Next Steps
- Learn about Session Keys
- Set up Multiple Signers for backup authentication
- Integrate Purchase Functionality for game monetization
- Customize your Controller
- Set up Usernames
- Configure Paymaster