Setup API Access

Get an API Key

The API is currently available to invited users only. To get an API key, get an invitation to the API console from the Axiom team and create a new key using your account.

Install the Axiom CLI and Initialize with your API Key

To use the Axiom Proving API from CLI, you must install the Axiom command line tool cargo-axiom using the following command. You should first make sure you have installed the necessary Prerequisites, notably including cargo-openvm.
cargo +1.86 install --locked --git https://github.com/axiom-crypto/axiom-api-cli.git --tag v1.0.0 cargo-axiom
To authenticate with the Axiom Proving API, run
cargo axiom register --api-key <API_KEY>
The API key can be passed in directly or by setting the AXIOM_API_KEY environment variable in a .env file.
AXIOM_API_KEY=<API_KEY>
Note that cargo axiom register should be run in the directory containing the .env file.

Register a Program

We will now walk through an example of generating a proof on the Axiom Proving API for an example Fibonacci guest program. First, initialize a new project:
cargo axiom init fibonacci
Note that this creates the Cargo.toml and adds openvm dependencies for you. The openvm version used depends on your local cargo openvm version, so make sure cargo openvm is up to date.

Building Your Program

Register your program with the Axiom Proving API to be reproducibly built with the default VM configuration ID with config-id = cfg_01k3w1spnpnxzry017g5jzcy97.
cargo axiom build --config-id cfg_01k3w1spnpnxzry017g5jzcy97
This will return a program-id and display the project information. You can check the build status with:
cargo axiom build status --program-id [program-id]
The status output will show both the program details and which project it belongs to:
Build Status:
  ID: prg_01k3r5vx20szgmn225k11hw8ez
  Name: bulky-piculet
  Project ID: prj_01k3r5vxwn4f1r3ekna6vs7ppd
  Project Name: abiding-magpie
  Status: ready
  ...
Alternatively, passing in --wait will poll the status automatically.
cargo axiom build --config-id cfg_01k3w1spnpnxzry017g5jzcy97 --wait

Understanding Projects vs Programs

The Axiom Proving API organizes your code into Projects and Programs:
  • Project: A logical container that groups related programs together. Projects have human-readable names like "fibonacci" and unique project IDs like prj_01k3r5vxwn4f1r3ekna6vs7ppd.
  • Program: A specific build of your code within a project. Programs have computer-generated names like "bulky-piculet" and program IDs like prg_01k3r5vx20szgmn225k11hw8ez.
The first time you run cargo axiom build, the CLI will prompt you for a project name and create the project accordingly. The project-id is stored locally at .axiom/project-id. On subsequent runs in the same directory, the CLI will reuse this project-id so new programs are added to the same project. To add a program to an existing project, add --project-id <ID> to your build command.

Generate a Proof

Next, request a proof from the Axiom Proving API:
cargo axiom prove --program-id [program-id] --type stark --input "0x010A00000000000000"
This will return a proof-id. You can check the status of the proving job with:
cargo axiom prove status --proof-id [proof-id]
Similarly using --wait polls the proving status automatically
cargo axiom prove --program-id [program-id] --type stark --input "0x010A00000000000000" --wait
Once the proving job is done, you can download the proof using:
cargo axiom prove download --proof-id [proof-id] --type stark --output proof.json
Finally, verify the proof is valid using:
cargo axiom verify stark --program-id [program-id] --proof proof.json

Installation Prerequisites

Prior to installing cargo-axiom, make sure you have the following packages installed:
# install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"

# install nightly Rust toolchain for binary builds
rustup install nightly-2025-02-14
rustup component add rust-src --toolchain nightly-2025-02-14

# install build tools for Ubuntu
sudo apt update
sudo apt install -y build-essential libssl-dev pkg-config   # gcc, g++, make, libc headers

# install cargo-openvm
cargo +1.86 install --locked --git https://github.com/openvm-org/openvm.git --tag v1.4.0 cargo-openvm