Skip to main content

Quick Start

Get your first transaction on Convex in 5 minutes.

Choose Your Path​

Pick the fastest way to get started based on your setup:

PathTimeBest For
Local Peer2 minDevelopers with Java installed
Testnet1 minQuick testing, no installation
SDK Quickstart5 minYour preferred language

Option 1: Local Peer​

Fastest for development - Run a peer in your JVM.

Prerequisites​

  • Java 21+ installed
  • Maven or Gradle (for Java examples)

Quick Start​

1. Add Dependency (Maven):

<dependency>
    <groupId>world.convex</groupId>
    <artifactId>convex-java</artifactId>
    <version>0.8.2</version>
</dependency>

2. Run Your First Transaction:

import convex.peer.Server;
import convex.api.Convex;
import convex.core.Result;
import convex.core.crypto.AKeyPair;
import convex.core.cvm.Address;
import convex.core.lang.Reader;

public class QuickStart {
    public static void main(String[] args) throws Exception {
        // Start local peer
        Server server = Server.create();
        server.launch();

        try {
            // Connect
            Convex convex = Convex.connect(server);

            // Create account
            AKeyPair keyPair = AKeyPair.generate();
            Address address = convex.createAccountSync(keyPair.getAccountKey());
            convex.setKeyPair(keyPair);
            convex.setAddress(address);

            // Your first transaction!
            Result result = convex.transact(
                Reader.read("(def greeting \"Hello Convex!\")")
            ).get();

            System.out.println("✓ Transaction succeeded!");
            System.out.println("Result: " + result.getValue());

            // Query the value
            Result query = convex.query(Reader.read("greeting")).get();
            System.out.println("Greeting: " + query.getValue());

        } finally {
            server.shutdown();
        }
    }
}

3. Run It:

mvn compile exec:java -Dexec.mainClass=QuickStart

Expected Output:

✓ Transaction succeeded!
Result: "Hello Convex!"
Greeting: "Hello Convex!"

🎉 Success! You've:

  • ✅ Started a local peer
  • ✅ Created an account
  • ✅ Submitted a transaction
  • ✅ Queried network state

Next: Explore Local Testnets for more options.

Option 2: Hugging Face Testnet​

No installation needed - Connect to public testnet.

Any Language​

1. Install SDK:

# TypeScript/JavaScript
npm install @convex-world/convex-ts

# Python
pip install convex-api

2. Connect and Transact:

TypeScript:

import { Convex, KeyPair } from '@convex-world/convex-ts';

// Connect to testnet
const convex = new Convex('https://mikera1337-convex-testnet.hf.space');

// Create account
const keyPair = KeyPair.generate();
// Note: You'll need to request an account from the faucet
// See Faucet Guide for details

// Your first transaction
const result = await convex.transact('(def greeting "Hello Convex!")');
console.log('✓ Transaction succeeded!');
console.log('Result:', result.value);

// Query
const query = await convex.query('greeting');
console.log('Greeting:', query.value);

Python:

from convex_api import Convex, KeyPair

# Connect to testnet
convex = Convex('https://mikera1337-convex-testnet.hf.space')

# Create account
key_pair = KeyPair()
# Note: Request account from faucet - see Faucet Guide

# Your first transaction
result = convex.transact('(def greeting "Hello Convex!")')
print('✓ Transaction succeeded!')
print('Result:', result.value)

# Query
query = convex.query('greeting')
print('Greeting:', query.value)

Java:

import convex.api.Convex;
import convex.core.Result;
import convex.core.lang.Reader;

// Connect to testnet
Convex convex = Convex.connect("https://mikera1337-convex-testnet.hf.space");

// Create account and request funds from faucet
// See Faucet Guide for details

// Your first transaction
Result result = convex.transact(
    Reader.read("(def greeting \"Hello Convex!\")")
).get();

System.out.println("✓ Transaction succeeded!");
System.out.println("Result: " + result.getValue());

// Query
Result query = convex.query(Reader.read("greeting")).get();
System.out.println("Greeting: " + query.getValue());

Note: Public testnets require account creation via faucet. See Faucet Guide for details.

🎉 Success! You've connected to a public network!

Next: Read the Networks Guide to understand network types.

Option 3: Language-Specific​

Deep dive - Complete quickstart for your language.

Choose Your Language​

Java (Recommended for local development)

  • ✅ Fastest performance
  • ✅ Full local peer control
  • ✅ Best for backend/Android
  • → Java Quickstart

TypeScript (Recommended for web apps)

Python (Recommended for scripts)

  • ✅ Simple syntax
  • ✅ Great for automation
  • ✅ Best for scripting/data science
  • → Python Quickstart

Understanding What You Did​

Key Concepts​

Account

  • Your identity on Convex
  • Holds Convex Coins (CVM)
  • Identified by address (e.g., #1234)

Key Pair

  • Ed25519 public/private keys
  • Private key signs transactions
  • Public key creates account

Transaction

  • Modifies network state
  • Requires funded account
  • Costs juice (execution fee)

Query

  • Reads network state
  • Free (no account needed)
  • Doesn't modify anything

What Just Happened?​

(def greeting "Hello Convex!")

This Convex Lisp code:

  1. Defined a variable greeting
  2. Stored it in global state
  3. Persisted across the network

Your transaction was:

  • ✅ Cryptographically signed
  • ✅ Validated by consensus
  • ✅ Permanently recorded

Next Steps​

Learn More​

Understand the Network

Master Your SDK

Write Smart Contracts

Try These Next​

1. Check an Account Balance

(balance #13)

2. Do Some Math

(+ 1 2 3 4 5)

3. Create a Function

(defn square [x]
  (* x x))

(square 7)

4. Deploy a Smart Contract

(deploy
  '(do
     (defn greet [name]
       (str "Hello, " name "!"))
     (export greet)))

Troubleshooting​

Connection Failed​

Local Peer:

  • Check Java 21+ installed: java -version
  • Increase memory: -Xmx4g
  • Check port 18888 not in use

Testnet:

  • Verify network URL correct
  • Check internet connection
  • Try alternative testnet

Transaction Failed​

FUNDS Error:

  • Account needs Convex Coins
  • Local peer: accounts created with funds
  • Testnet: request from faucet

SEQUENCE Error:

  • Don't submit concurrent transactions
  • Wait for previous transaction to complete

Can't Query​

Check:

  • Network connection established
  • Query syntax correct
  • Variable/function exists

Get Help​

Resources:

Common Questions:

  • What's a CVM? → The Convex Virtual Machine
  • What's juice? → Transaction execution cost
  • What's copper? → Smallest unit of CVM (1 CVM = 1B copper)
  • What's a peer? → A network node

🎉 Congratulations! You're now part of the Convex network. Build something amazing!