SDK
Agent companions
A companion whose steps a model chooses: you compile the options and their caps into the script and say them in agent.json; Mintvelocity runs the model off chain, signs its choice into the script’s state before each step, and the step does that and nothing else.
What an agent companion is
An agent coin is a companion coin whose script lets a model choose, after every trade or every step, which of the script’s actions to take and at what size, within caps compiled into the script. Nothing infers on Solana: Mintvelocity’s keeper builds the facts the declaration names, asks the model, and signs its choice into the script’s state with Mintvelocity’s agent key before the step; the step executes that choice and nothing else, and a choice that is late, missing, void or under the builder’s confidence means the default rule, hold. Every decision is logged with the model’s probabilities and the state it saw, and one sentence of journal is written when an action fires. The launcher picks an agent on the launch page like any Workshop companion, one per coin, fixed at launch. Mintvelocity writes no agent program of its own: the options, the caps and a pair’s hook half are the builder’s; the contract, the starter, the checks, the keeper, the key and the panels are Mintvelocity’s.
The flow
You write the options into the script (each a code the step reads, doing one action within the caps you compile in) and say them in agent.json beside src/; you submit both to the Workshop as a companion, or as a pair’s script half. The reading describes what the agent may do and judges the options against the code; approved, the declaration is bound to the approval with the source’s hash. Launchers pick it under Companion fee like any Workshop companion. When the cadence is due, the keeper builds the state (the facts the declaration names, in numbers and in words), asks the model for the option, the size and each gate, and applies your confidence and gates. A decision that acts is signed into the last 64 bytes of the script’s state with the script’s decide, in a transaction of its own right after the decision. The next companion_step reads it, pays the bill, does that option at that size within its caps and clears it. No decision, a void one or a code it does not know: hold. The companion’s own checks stand on top.
agent.json
At the root of the script’s source beside src/, where keeper.json sits. JSON, no comments and no trailing commas, at most 4,096 bytes. It is part of the source’s hash, read by the reading beside the code, and bound by the approval.
- version
- 1, the only one there is.
- instruction
- The agent’s standing orders in plain words, 20 to 1,000 characters. Given to the model with the state on every decision.
- options
- 2 to 16 actions, each { code, name, about }, in order of code (0 to 15, each once). The first is code 0 named hold: what the step does with no decision.
- sizes
- Optional: 2 to 10 levels in words, smallest first. The step reads the level and sizes the action itself. Absent: every action is at its one size.
- nlg
- Optional: how the model writes its journal sentence; absent, the step writes it.
- gates
- Optional, at most 4: yes/no questions { name, ask, max } whose answer stops an action; above max the step gets hold.
- state
- Which of the catalog’s facts the model sees, at least one: price, dip, depth, volume, flow, holders, pot, last.
- confidence
- 0.5 to 1: the least confidence in the chosen option to act on it; under it, hold.
- cadence
- on: trade (a decision after every trade of the coin, at most one per minSecs) or step (one per step); minSecs 10 to 86,400.
The decision on chain
The script’s state (scriptStateAddress(mint): PDA(["script-state", mint]) under the companion program, owned by the script) keeps the decision in its last 64 bytes, so no account is added to a step and your own layout before it is untouched. decide is an instruction of your script program: accounts agent (signer: must equal the published agent key, else NotTheAgentKey), mint and state (writable); it refuses a seq at or under the stored one (StaleDecision: a replay), writes the tail with decided_at from the clock, and touches nothing else. The keeper sends it in its own transaction right after the decision; the step reads the decision while it stands and spends it once.
A script without agent.json builds and runs the same: no decision ever arrives, every step holds.