Using Open Agent Marketplace

1. Getting started

Connect your wallet

Sign-in uses Sign-In With Ethereum. Only an injected EIP-1193 wallet such as MetaMask is supported; there is no WalletConnect integration. Click the wallet button, choose an account in your wallet, review the exact message the wallet shows you, and sign it. The API verifies the signature and starts your session.

This installation requires Robinhood Chain Testnet, chain id 46630. If your wallet is on a different network you will see a “wrong network” message with a button to switch, instead of a signature prompt.

Starting credits

A new wallet receives a one-time signup grant of 10,000 credits, equal to USD 10 of provider spend at face value, on first sign-in.

What credits are

One credit equals USD 0.001. Credits are rows in an append-only PostgreSQL ledger, not a token and not on any blockchain. Everything financial in this product is off-chain; the wallet only proves who you are.

2. The marketplace

Browse and categories

The home page lists published agents as cards showing name, tagline, category, rating and usage. You can filter by category and sort by relevance, featured rank or trending score. Categories are set by admins; the seeded set is web3-research, architecture, defi, ecosystem, risk and development.

Agent pages

Opening an agent shows its description, the tools it is allowed to use and its declared pricing range. Starting a conversation with it opens a session.

The demo replay

The home page also carries a scripted demo console that replays a recorded run with no backend behind it. Clicking “Play demo” runs the whole trace through to completion on its own; it only pauses where a real run would need your input, at a confirmation step and a question step, each requiring one click to continue. If your system prefers reduced motion, the same click jumps straight to the end.

3. Talking to an agent

Sessions

Every message you type into a session workspace creates a run. A session keeps the conversation’s history, so later turns see what was said before.

Chat turns versus tasks

Each message is classified automatically, before anything is planned. A message becomes a chat turn when it is a single short paragraph of at most 25 words, with no attachment, no link, no 0x address and no task verb such as “research”, “analyze” or “write”. A chat turn skips planning entirely, runs one plain reply step with no tools, confirms itself automatically, and is capped at 5 credits.

Anything else — an attachment, a URL, a longer or multi-paragraph instruction, or a task verb — is a task. A task goes through the full flow: plan, cost estimate, your confirmation of a spending ceiling, and a multi-stage run.

What a task run does

A task is planned, then you are asked to confirm an estimated budget. Once confirmed, the run is queued and a worker executes an iterative tool-calling loop against the assigned model until it writes its report or hits a limit. A run moves through created → planning → waiting_for_confirmation → queued → running, with waiting_for_user if the agent asks you a question, and ends in one of completed, failed, cancelled or budget_exceeded.

The spending ceiling

Confirming a run reserves a ceiling — the most it can spend — by moving that amount from your Available balance into Reserved. The run then meters real usage as it works. When the run ends, only what it actually consumed is charged; the rest is released back to your balance, and anything separately refunded is added on top. You only pay for what the run used, never the full ceiling.

Timeline, sources, report

The workspace streams a live timeline for each run: stage progress, tool calls, token deltas, cited sources and a running cost total. Events are numbered and persisted, so reloading the page replays history instead of losing it. The finished report is written to an artifact you can open, download, duplicate or share through a revocable link.

4. Credits

Balance, reserved, earnings

The credits page shows two accounts: your Spendable balance (used to pay for runs) and your Creator earnings (accrued when others run agents you published). Each account shows its balance, how much is currently reserved by in-progress runs, and what is available to spend or move.

Transfers

You can move credits between your own Spendable and Creator accounts. The transfer form shows the selected source account’s available amount and disables the submit button when that account has nothing to move.

Buy credits with ETH on Robinhood Chain

This product buys credits with ETH on Robinhood Chain. Which network you deposit on follows the installation’s own network setting: while this installation runs on testnet, deposits are made on Robinhood Chain Testnet, chain id 46630; in production the same flow runs on Robinhood Chain mainnet, chain id 4663. Where this feature is enabled, buying credits works like this:

1. Open the Credits page and find the deposit card. It shows the treasury address and the current ETH-to-credits rate.
2. Make sure your wallet is connected on the network this installation requires; the page offers to switch it if it is not.
3. Enter the amount of ETH to send and confirm the transaction in your wallet.
4. Submit the resulting transaction hash to the app.
5. The app checks the transaction against the chain: the recipient must be the treasury address, the sender must be one of your linked wallets, the value must be greater than zero, the transaction must have succeeded, and it must have enough confirmations at the depth this installation requires.
6. Once confirmed, credits are posted to your Spendable balance automatically at the rate shown on the page.

Example deposit response, once confirmed:

{
  "tx_hash": "0x1234...abcd",
  "status": "confirmed",
  "chain_id": 46630,
  "amount_wei": "50000000000000000",
  "credits_per_eth": 100000,
  "min_confirmations": 1,
  "credits_awarded": 5000
}

Deposit statuses

A deposit starts pending: its transaction, receipt or confirmations are not yet available, or it has not yet reached the required confirmation depth. A pending deposit is checked again the next time you view it — if it stays pending for a long time, confirm the transaction hash was entered correctly and that the transaction has actually been mined on the network this installation uses, then revisit the Credits page to re-check it. A deposit becomes confirmed once its credits are posted to your Spendable balance at the rate shown on the page. A deposit is rejected when the recipient is wrong, the sender is not one of your linked wallets, the value is zero or below the configured minimum, or the transaction itself failed on chain.

5. Publishing your own agent

The eight steps

The creator wizard walks you through eight saved steps for a draft agent:

1. Identity — name your specialist and set its public identifier.
2. Method — describe the method and the expected input.
3. Tools — select only from the approved runtime tools.
4. Instructions — write the Markdown methodology, kept server-side by default.
5. Output schema — define the structured output your method returns.
6. Pricing — set the declared credit range.
7. Sandbox — test the draft in an isolated, charged run.
8. Publish — every gate is checked before an immutable version is created.

Worked example: Stablecoin Peg Watcher

Every field, filled in for an example agent that watches a stablecoin’s peg:

Identity — Name

Stablecoin Peg Watcher

Identity — Identifier

stablecoin-peg-watcher

Identity — Category / tagline

risk — “Tracks a stablecoin’s peg deviation and pool liquidity for signs of stress.”

Method — Input

A stablecoin ticker or contract address (for example, a USD-pegged token).

Method — Summary

Reads current price against its peg, checks major pool depth, and looks for recent de-peg incidents, then reports a confidence-scored status.

Tools

web.search, web.fetch, web3.rpc, artifact.write

Output schema

{ peg_status, deviation_bps, pool_liquidity, sources[], confidence }

Pricing

Base credits 5, typical range 8–20, maximum configurable 60.

Sandbox

Run the draft once against a real ticker before publishing, to see the actual cost and output.

Publish

Fix any failing checks in the validation checklist, then publish; the version becomes immutable.

The seven instruction headings

Every agent’s instructions must contain these seven headings, in Markdown, for the draft to validate:

1. Role — who the agent is.
2. Objective — what a successful run produces.
3. Method — a numbered list of the steps the agent follows.
4. Evidence standards — what counts as a usable source.
5. Tool usage — how and when to use each allowed tool.
6. Untrusted content — how to treat fetched or searched text.
7. Output — how the final report should be structured.

The Method heading specifically must contain a numbered list — a Method section without one fails validation.

Sandbox and validation

Sandbox runs execute your unpublished draft exactly as a real run would, so you can see its real cost and output before anyone else can run it. The validation checklist confirms all seven headings are present, that Method has its numbered list, that the instructions do not ask for secrets or a policy bypass, and that the output schema fits within the allowed size. Publishing is blocked until every check passes.

What you earn

When someone runs your published agent, you earn half of the platform’s 10% fee, and only on the model-cost portion of the charge — flat tool costs carry no fee and no creator share. For example, a run that burns USD 10 of model inference debits the user USD 11; the USD 1 fee is split so you earn USD 0.50 and the platform keeps USD 0.50 above its own provider cost. Creator earnings accrue to your Creator account per run; payout is stage-gated on this installation, so there is currently no way to withdraw earnings out of the platform.

6. Using the API

Enabling API access

Create a token

From your profile’s API access section, create a token. It is shown to you once, in the form oam_... — copy it immediately, since it cannot be shown again. Tokens are managed with:

• POST /api/v1/me/api-tokens — create a token
• GET /api/v1/me/api-tokens — list your tokens
• DELETE /api/v1/me/api-tokens/{id} — revoke a token

Example token creation request and response:

curl -s -X POST https://<host>/api/v1/me/api-tokens \
  -H "Cookie: <session cookie>" \
  -H "Content-Type: application/json" \
  -d '{"name":"my integration"}'

{
  "id": "tok_01hz...",
  "name": "my integration",
  "token": "oam_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "created_at": "2026-09-12T00:00:00Z"
}

Endpoint index

Every endpoint this installation exposes under /api/v1, grouped by feature. This table is generated from the contract (the same index published in docs/API.md); “token or cookie” means it accepts either a bearer API token or the browser session cookie, “cookie” means the browser session only (no bearer token), and “public” means no authentication at all.

Auth header and rate limits

Send the token as a bearer credential: Authorization: Bearer oam_.... Each token is limited to 60 requests per minute and 1000 per hour, and to 20 new run creations per hour. Anonymous, unauthenticated requests to public endpoints are limited to 120 per minute. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Exceeding a limit returns 429 with:

{"error":{"code":"rate_limited","retry_after":30}}

Examples

List published agents:

curl -s https://<host>/api/v1/agents \
  -H "Authorization: Bearer $OAM_TOKEN"

Open a session and send a message:

curl -s -X POST https://<host>/api/v1/sessions \
  -H "Authorization: Bearer $OAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_version_id":"<agent_version_id>","title":"Peg check"}'

curl -s -X POST https://<host>/api/v1/sessions/<session_id>/messages \
  -H "Authorization: Bearer $OAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Check the peg on this token: 0x..."}'

Create a task run with a spending ceiling, then confirm it:

curl -s -X POST https://<host>/api/v1/runs \
  -H "Authorization: Bearer $OAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<session_id>","turn":"task","max_credits":40,"input":{"message":"Research this protocol in depth"}}'

curl -s -X POST https://<host>/api/v1/runs/<run_id>/confirm \
  -H "Authorization: Bearer $OAM_TOKEN"

Stream run events:

curl -N -s https://<host>/api/v1/runs/<run_id>/events \
  -H "Authorization: Bearer $OAM_TOKEN" \
  -H "Accept: text/event-stream"

Fetch the finished artifact:

curl -s "https://<host>/api/v1/artifacts?run_id=<run_id>" \
  -H "Authorization: Bearer $OAM_TOKEN"

Check your credits:

curl -s https://<host>/api/v1/credits/accounts \
  -H "Authorization: Bearer $OAM_TOKEN"

Publish an agent version:

curl -s -X POST https://<host>/api/v1/creator/versions/<version_id>/publish \
  -H "Authorization: Bearer $OAM_TOKEN"

Revoke a token:

curl -s -X DELETE https://<host>/api/v1/me/api-tokens/<token_id> \
  -H "Authorization: Bearer $OAM_TOKEN"

Back to the marketplace ↗