Getting started with Idios

What you need before you start

Before you can create or accept a contract on Idios you need three things:

• Beam Desktop wallet installed from beam.mw. This is the wallet Idios runs inside. Available for Windows, Mac, and Linux.
• Idios dapp. Download idios.dapp. Once Beam Desktop is open and synced to mainnet, click the settings cog, then Install dapp. A dialog appears where you can drag the file or click to browse. Select the downloaded idios.dapp file. If an older Idios is already installed, remove it first, then install the new file.
• BEAM or NPH in your wallet. You need a small amount of BEAM to cover network fees (roughly 0.021 BEAM per contract action). Contract payments can be in BEAM or NPH. NPH is a USD-pegged confidential stablecoin available via the DEX tab inside Beam Desktop. See where to get BEAM if you need it.

Finding a worker via Idios Market

If you do not already have a counterparty, Idios Market is where workers list themselves and clients post jobs.

Everything up to this point is off-chain. The marketplace is just a directory. No funds are involved until you create a contract in the Idios dapp.

The two contract types

Idios has two settlement modes. You choose when creating the contract.

Mode B: Reviewed settlement, start to finish

The scenario

A company called NovaCRM wants to automate their sales outreach. They need a custom AI agent built in Python using LangChain and the GPT-4 API. The agent should qualify inbound leads from their CRM, draft personalised follow-up emails, and log outcomes back to the database.

They find a freelance AI developer named Priya on Idios Market. They agree on 2 NPH payment. Priya will put up 1 NPH as collateral. The full project scope is documented in a brief they exchange off-chain via Telegram.

NovaCRM does not want this project visible on-chain. A competitor seeing they are building AI sales automation before launch would be a problem. Priya does not want her client list public.

Step 1: NovaCRM creates the contract

Priya sends NovaCRM her Beam pubkey from the Idios dapp landing page. NovaCRM opens Idios, clicks Start a contract, and fills in:

• Contract ID: any number they choose, e.g. 88801
• Settlement type: Reviewed (Mode B)
• Payment: 2 NPH
• Payment asset: NPH
• Priya's pubkey: the key Priya sent them
• Expiry block: current block + 20,000 (about two weeks)
• Review window: 2,000 blocks (about 33 hours to approve or dispute after delivery)
• Dispute fee: 0.1 NPH (locked if NovaCRM disputes; win or lose, the fee pays the arbitrators for judging the dispute)

NovaCRM clicks Create Contract. Their wallet asks them to confirm locking 2 NPH. They confirm. The contract is on-chain. Their payment is locked. Priya can see the contract exists and the terms.

Step 2: Priya commits her collateral

NovaCRM shares the contract ID (88801) with Priya off-chain. Priya opens Idios, goes to My Contracts, and adds contract 88801 as worker. She clicks Commit, locking her 1 NPH collateral.

Both sides now have skin in the game. Priya cannot walk away without losing her collateral. NovaCRM cannot disappear with Priya's time for free.

Step 3: Priya builds the agent and delivers

Priya spends a week building the agent. The final deliverable is a ZIP file containing the full codebase, a README, and a deployment guide.

She generates the hash of her ZIP before submitting:

sha256sum novacrm_agent_88801.zip

Output: f29a4c81...7e02

She pastes that hash into Idios and clicks Submit Delivery. The contract status moves to Awaiting Approval.

Priya then sends the actual ZIP to NovaCRM however they agreed. The code never touches the blockchain.

Step 4: NovaCRM reviews and approves

NovaCRM downloads the ZIP, deploys the agent in a test environment, verifies it works, then opens Idios and clicks Approve Delivery.

The contract moves to Settled. Priya clicks Claim Funds and receives 2 NPH payment plus her 1 NPH collateral back. Total: 3 NPH. Both balances update privately on-chain.

The four ways a Mode B contract can resolve

All four paths are enforced by the contract. Neither party can exit by simply walking away.

What if the work is bad?

NovaCRM clicks Dispute. They pay the 0.1 NPH dispute fee. They contact the arbitrator off-chain at @tappyoak on Telegram or Discord to explain the problem. The arbitrators review the situation and resolve on-chain by voting.

If the arbitrators side with NovaCRM: they get their 2 NPH back plus Priya's 1 NPH collateral, 3 NPH total. Priya walks away with nothing.

If the arbitrators side with Priya: Priya gets the 2 NPH payment plus her 1 NPH collateral, 3 NPH total. Either way the 0.1 NPH dispute fee goes to the voting arbitrators as payment for judging the dispute.

Mode A: Hash-verified settlement, start to finish

Why Mode A exists

Mode A solves a specific problem: what if the expected output is fully known before the contract starts?

If you are buying a fine-tuned model and both parties already know what the model weights file should look like, including its exact checksum, there is no need for anyone to review the delivery. The contract verifies it automatically. No human approval. No waiting. This makes Idios useful for AI data vendors, model marketplaces, and autonomous agent pipelines.

The scenario

A startup called VisionAI has trained a custom image classification model. They are selling it to a research lab called MedResearch for 5 NPH. Before the contract is created, VisionAI sends MedResearch a small sample of the model and its SHA-256 hash privately: a4f7e2b1...9c03. MedResearch verifies the sample and agrees this is the file they want to buy.

Neither party wants this transaction public. MedResearch does not want competitors knowing they are acquiring this model. VisionAI does not want their client list visible.

The key difference from Mode B

In Mode B the delivery hash is submitted after the work is done. In Mode A the expected result hash is locked into the contract by the buyer when they create it. The seller cannot change it. The only way to get paid is to deliver the file that produces exactly that hash.

Step 1: MedResearch creates the contract

MedResearch opens Idios, clicks Start a contract, selects Hash-verified, and fills in:

• Contract ID: 88802
• Settlement type: Hash-verified (Mode A)
• Payment: 5 NPH
• VisionAI's pubkey: provided by VisionAI
• Expiry block: current block + 3,000
• Result hash: a4f7e2b1...9c03

Their 5 NPH payment is locked. VisionAI can see the contract.

Step 2: VisionAI commits collateral

VisionAI finds contract 88802 in Idios and commits 2.5 NPH collateral. They now have 2.5 NPH at risk. If they deliver the wrong file, they lose it.

Step 3: VisionAI delivers

VisionAI generates the hash of their model file:

sha256sum vision_classifier_v2.bin

Output: a4f7e2b1...9c03

This matches the result hash MedResearch locked in. VisionAI submits this hash to Idios. The contract checks: does delivery_hash == result_hash? Yes. Payment releases automatically. 5 NPH payment plus 2.5 NPH collateral goes to VisionAI. Total: 7.5 NPH. Nobody clicked approve.

VisionAI then sends the actual model file to MedResearch however they agreed. The file never touches the blockchain.

Generating a SHA-256 hash

On Linux or Mac:

sha256sum yourfile.bin

On Windows (PowerShell):

Get-FileHash yourfile.bin -Algorithm SHA256

The output is always a 64-character hex string. The same file always produces the same hash. Change a single byte and the entire hash changes.

The collateral and why it matters

In every other AI freelance platform, only the buyer's funds are at risk. A developer can take a job, disappear, or deliver broken code, and their only consequence is a lower rating. They make a new account and start again.

In Idios the worker locks collateral before they can submit delivery. If the dispute goes against them they lose it. A developer who has locked 1 NPH has a direct financial reason to deliver working code. A developer who has not locked anything does not.

The collateral amount is set when the contract is created. The dapp defaults to 50% of the payment. For high-trust repeat work you might lower it. For a first engagement with an unknown party you might raise it.

Quick reference

Action	Who	When
Create contract	Requester	Before work starts, locks payment
Commit collateral	Worker	After creation, locks collateral
Submit delivery	Worker	When work is done, submits hash
Approve	Requester	Mode B only, after reviewing work
Dispute	Requester	Mode B only, if work is unsatisfactory
Vote	Arbitrators	After dispute; resolves to whichever side reaches the vote threshold
Claim after timeout	Worker	Mode B only, if requester never responds
Claim funds	Worker	After settlement or resolve in worker's favour
Refund	Requester	After expiry if no delivery; a committed worker forfeits collateral to the treasury

Frequently asked questions

Does the actual work get stored on-chain?

No. Only the hash (fingerprint) of the deliverable is stored. The actual file, codebase, or model is exchanged off-chain however the two parties agree.

Can I use NPH instead of BEAM?

Yes. When creating a contract, select NPH as the payment asset. NPH is a USD-pegged confidential stablecoin on Beam. Get NPH via the DEX tab in your Beam Desktop wallet.

How do I get my Beam pubkey?

Open the Idios dapp in Beam Desktop. Your pubkey is shown on the landing page. It is contract-specific, meaning the pubkey shown in Idios is different from your general Beam wallet address. Always use the pubkey from the Idios dapp, not your wallet address.

What if the worker commits collateral and then disappears?

The contract expires at the block you set. After expiry, if no delivery was submitted, you click Refund and get your payment back. If the worker had committed collateral, that collateral is forfeited to the treasury. It does not return to the worker and it does not come to you. That forfeit is the penalty for committing and then going silent, and it happens on the refund itself, no dispute needed. If no worker ever committed, Refund just returns your payment and there is no collateral in play.

What if both parties disagree about whether the work meets the spec?

The requester files a dispute and pays the dispute fee. The arbitrators review the situation off-chain and resolve on-chain by voting. The winner receives the payment plus the collateral; the dispute fee pays the voting arbitrators. Contact the arbitrator at @tappyoak on Telegram or Discord with the contract ID, your role, and a description of the dispute.

How long do transactions take to confirm?

Each on-chain action typically confirms within one to two Beam blocks, usually a few minutes. The review window (e.g. 2,000 blocks, about 33 hours) is separate. That is the time the requester has to approve or dispute after delivery. The transaction itself is fast. The review window is a deliberate waiting period.

Can I cancel a contract after creating it?

Not directly. Once created the payment is locked. If the worker never commits their collateral, you can refund after the expiry block passes. If the worker has already committed, both sides are locked in until delivery, approval, dispute, or expiry.

What if I approve work and then regret it?

Once you approve, the worker can claim funds and you cannot reverse it. Test the deliverable thoroughly before approving.

Is my transaction history private?

Yes. Beam's MimbleWimble protocol hides amounts and counterparty identities at the base layer. No one can see what you paid, who you paid, or how much the collateral was. This is not a mixer or add-on. Privacy is built into the Beam protocol itself.

What stops the requester from downloading the work and not paying?

The order of operations. The worker submits the delivery hash on-chain first, locking the contract into Awaiting Approval. Only then do they send the actual file. The requester cannot get their payment back without either approving (worker gets paid) or disputing (arbitrator decides). If they do nothing, the worker claims after the review window expires. The requester's payment and the worker's collateral are both locked until the contract resolves.

Does Idios take a fee?

No. The contract charges no platform fee. You pay only the standard Beam network transaction fee, typically 0.021 BEAM per action.

Who is the arbitrator?

Dispute resolution uses an M of N arbitrator registry on the contract, with one arbitrator registered today. Contact @tappyoak on Telegram or Discord to raise a dispute. Include the contract ID, your role, and a brief description of the situation.

Can my funds be frozen?

No. Idios uses BEAM and NPH. Neither asset has a central issuer with blacklist functions. Unlike USDC or USDT, no third party can freeze your funds in an Idios contract.