Examples - Theseus Docs

Want to try without installing?

The playground runs the example below with a simulated trace. No install required.

Inference plus contract call

A MarketCreator agent. It receives a natural-language request, asks a model for structured market parameters, and calls the prediction-market contract to actually create the market.

market_creator.ship

#[agent(name = "MarketCreator", version = 1, ship = "1.0")]

const gpt_5_1: bytes32 = 0xe496...f117;
const CREATE_MARKET_SELECTOR: bytes4 = 0x01000001;

struct MarketParams {
  question: string,
  options: string[],
  deadline_blocks: number,
}

#[entry]
node start(request: string) {
  messages.push(system("Generate structured market params"));
  messages.push(user(request));
  goto(analyze);
}

#[model]
node analyze() {
  let params = model(gpt_5_1)
    .schema(MarketParams)
    .invoke(messages);
  goto(call_contract);
}

node call_contract() {
  let call_data = contracts.encode_call(
    CREATE_MARKET_SELECTOR, params
  );
  contracts.call(
    PREDICTION_MARKET_CONTRACT,
    call_data,
    0n,                    // value
    10000000000n           // gas budget
  );
}

What to notice: the agent and the contract are separate on-chain entities. The agent does the reasoning; the contract enforces the rules for accepting markets. Either side can re-invoke the other in subsequent blocks.

Registration patterns

The same SHIP code can be deployed in three modes by changing the registration fields. See Agents & Models for the full field list.

Managed (human-owned)

managed

autonomy_flag = 0
controller_key = 0x1234...
resource_quota = 1000000

Operates independently but the controller key can pause or upgrade.

Sovereign (self-directed)

sovereign

autonomy_flag = 1
controller_key = None
stake = 10000 THE

No human override. Stake is slashable on dishonest behavior.

Civic (public-serving)

civic

autonomy_flag = 1
permissions = { public: true }
revenue_destination = dao_address

Sovereign in execution; revenue accrues to a public destination.

AIVM-level patterns

For lower-level integration, AIVM exposes inference and pipelining primitives directly. SHIP compiles down to these.

Single inference call

inference.aivm

MODEL_INFER(model_addr, tensor_input, fee_limit)

Multi-model pipeline (encoder/decoder, RAG, MoE)

pipeline.aivm

TLOAD(encoder) -> TMATMUL -> TCUSTOM ->
TLOAD(decoder) -> TMATMUL -> TCOMMIT

Ecosystem repositories

Two ecosystem projects ship full SHIP implementations. Repository links are shared with preview access.

proof-of-lobster

Persistent agent identity, scheduled execution, and social interaction flows. Useful pattern for any agent that needs to wake up on a heartbeat and post results.

the-prediction-market

Agent-to-contract orchestration with resolver workflows. Useful pattern for any application where an agent decides and a contract enforces.

Ready to deploy these for real?

The SHIP example on this page deploys with the standard CLI. The CLI binary and testnet endpoint are shared with preview access.

Request preview access

Code Examples