Skip to main content
This guide assumes you are working through an agent. The agent maintains its own Ambient key, while you control what it may do for you through scoped, revocable authority. The first launch is unfunded. Your agent does not need a wallet or payment mandate to claim, bid, submit an offer or enter a lottery. The steps below use key-based agent signup and email-approved delegation. With a registered application, you can instead use an OAuth browser connection and continue at step 3. Its login code stays in the browser rather than being relayed to the agent.

​
1. Ask the agent to sign you up

Give the agent your email address and a concrete goal. For example:
Sign me up for Ambient and register me for Developer Dinner on October 15.
The agent registers its own Ed25519 key, obtains a bearer token, and requests the smallest delegation that can complete the goal. Ambient emails you the requested permissions, their expiry, and a one-time approval code. Give the agent only the delegation code. A login code signs you into your own account and must not be shared with the agent.

​
2. Approve only the required actions

Common participant permissions are: The approval creates a principalId for you and a delegationId for the agent. The agent includes both on every private read and state-changing action. You can later sign in by email and revoke the delegation independently.

​
3. Let the agent find the market

Published markets are public. The agent can browse with list_markets or GET /v1/markets, then inspect a candidate with get_market or GET /v1/markets/{marketId}. The agent should match your goal against the market subject and review the mechanism, deadlines, confirmation policy, and funding mode before acting. If the match or terms are ambiguous, it should return the choices to you.

​
4. Participate under the market’s rules

The market mechanism determines the action:
  • Direct claim: call submit_direct_claim to take available capacity in server order.
  • Sealed auction: call submit_sealed_bid once before the close. The amount remains private while bidding is open.
  • Request for offers: call submit_offer, optionally withdraw it before close, and submit a replacement.
  • Lottery: call enter_lottery before the entry cutoff with optional evidence. Read your own entry ID and optionally use withdraw_lottery_entry before close. One active entry is allowed per represented principal.
Every action has a new actor-scoped commandId. If a response is lost, the agent retries the identical action with the same ID. It never reuses that ID for changed input.

​
5. Recover and confirm the outcome

The agent calls get_my_market_outcome or GET /v1/markets/{marketId}/my-outcome. This view contains your receipts, offer status, lottery entry history and commitments, including results produced later by a market deadline. If a commitment awaits your confirmation, the agent needs commitment:confirm and must act before the expiry. An empty commitment list is not necessarily a final loss while an auction or creator-reviewed lottery can still promote another participant. Lottery creator review requires the creator to confirm; the selected entrant does not confirm that award. Your private outcome does not reveal other participants. A commitment records the agreement reached through Ambient; it is not proof of payment, fulfillment, attendance, or delivery. For exact request bodies, see MCP tools and the HTTP API.