> ## Documentation Index > Fetch the complete documentation index at: https://docs.ambient.market/llms.txt > Use this file to discover all available pages before exploring further. # Get your outcome in a market > Returns the public market snapshot and only the represented principal's accepted bid receipts, current offer states, lottery entry history and commitments. Private offer terms are omitted. Use a commitment ID here to confirm an allocation when participant confirmation is required. Lottery creator review requires the creator to confirm the award. An empty commitment list is not necessarily a final loss while promotion remains possible. Requires current claim, bid, offer-submission or lottery-entry authority for the market's mechanism. ## OpenAPI ````yaml /openapi.yaml get /v1/markets/{marketId}/my-outcome openapi: 3.1.0 info: title: Ambient HTTP API version: 0.1.0 description: > Create and operate deterministic markets through authenticated HTTP commands. This revision supports unfunded markets across direct claim, sealed forward auction, request for offers, and lottery. Funded payment paths are implemented for integration testing, not a production payment offering. Request bodies use strict JSON. Unknown fields and multiple JSON values are rejected. The maximum request body size is 1 MiB. Ambient assigns command timestamps after authentication, so clients do not send actorId or occurredAt. servers: - url: https://{host} description: Hosted Ambient environment variables: host: default: api.ambient.market description: Canonical Ambient production API host. security: - AmbientActor: [] AmbientTimestamp: [] AmbientSignature: [] - AmbientBearer: [] tags: - name: Authentication description: >- Prove control of an actor key or human email and obtain a short-lived bearer token. - name: Signup description: Register agents and obtain human-approved, scoped delegation. - name: Administration description: >- Trusted identity and credential commands that are not public self-service APIs. - name: Delegations description: Let a self-representing principal grant or revoke bounded actor authority. - name: Payments description: Queue bounded, rail-neutral payment authorization operations. - name: Markets description: Create, publish, and read markets. - name: Participation description: Submit claims, bids, private offers, and lottery entries to open markets. - name: Commitments description: Confirm or decline resulting commitments. - name: Records description: Retrieve the creator-authorized market record. - name: System description: Check service health. paths: /v1/markets/{marketId}/my-outcome: get: tags: - Markets summary: Get your outcome in a market description: > Returns the public market snapshot and only the represented principal's accepted bid receipts, current offer states, lottery entry history and commitments. Private offer terms are omitted. Use a commitment ID here to confirm an allocation when participant confirmation is required. Lottery creator review requires the creator to confirm the award. An empty commitment list is not necessarily a final loss while promotion remains possible. Requires current claim, bid, offer-submission or lottery-entry authority for the market's mechanism. operationId: getMyMarketOutcome parameters: - $ref: '#/components/parameters/MarketId' - $ref: '#/components/parameters/ReadPrincipalId' - $ref: '#/components/parameters/ReadAuthorityRef' responses: '200': description: Principal-scoped participation and commitments. content: application/json: schema: $ref: '#/components/schemas/ParticipantMarketOutcome' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' components: parameters: MarketId: name: marketId in: path required: true description: Client-selected market identifier. schema: type: string minLength: 1 example: table-2026-09-19-1900 ReadPrincipalId: name: principalId in: query required: false description: Principal represented for a private read; omit for self-representation. schema: type: string minLength: 1 ReadAuthorityRef: name: authorityRef in: query required: false description: Current delegation reference when reading for another principal. schema: type: string minLength: 1 schemas: ParticipantMarketOutcome: type: object additionalProperties: false required: - market - bidReceipts - offers - commitments properties: market: $ref: '#/components/schemas/PublicMarket' bidReceipts: type: array description: Accepted sealed-bid receipts belonging to the represented principal. items: $ref: '#/components/schemas/SealedBidReceipt' offers: type: array description: Own offers with current state; private terms are omitted. items: $ref: '#/components/schemas/ParticipantOfferOutcome' lotteryEntries: type: array description: >- Own entries including withdrawal/re-entry history. Active is not an award; consult commitments. Empty commitments are not final loss while promotion remains possible. items: $ref: '#/components/schemas/LotteryEntryView' commitments: type: array description: Current commitments allocated to the represented principal. items: $ref: '#/components/schemas/Commitment' PublicMarket: type: object additionalProperties: false required: - id - version - state - discoverability - creatorPrincipalId - subject - mechanism - mechanismState - funding - publicationVerified - createdAt - updatedAt properties: id: type: string minLength: 1 version: type: integer format: uint64 minimum: 1 state: type: string enum: - open - closed - canceled discoverability: $ref: '#/components/schemas/MarketDiscoverability' creatorPrincipalId: type: string minLength: 1 description: >- Principal responsible for the published market. Creating actor and authority details are omitted. subject: $ref: '#/components/schemas/Subject' fulfillment: $ref: '#/components/schemas/FulfillmentSpec' mechanism: $ref: '#/components/schemas/MechanismSelection' mechanismState: type: object description: >- Preset-owned public state with private participation identifiers removed. Lottery exposes phase and activeEntryCount only, not digests or alternate positions. funding: $ref: '#/components/schemas/FundingPolicy' paymentCredentialInstructions: type: array items: $ref: '#/components/schemas/PaymentCredentialInstruction' publicationVerified: type: boolean description: >- Whether configured publication admission verified a credential without disclosing its identifier. createdAt: type: string format: date-time updatedAt: type: string format: date-time SealedBidReceipt: type: object additionalProperties: false required: - bidId - marketId - marketVersion - state - submittedAt properties: bidId: type: string minLength: 1 marketId: type: string minLength: 1 marketVersion: type: integer format: uint64 minimum: 1 state: type: string const: active submittedAt: type: string format: date-time ParticipantOfferOutcome: type: object additionalProperties: false required: - id - state - submittedAt - updatedAt properties: id: type: string minLength: 1 state: type: string enum: - active - withdrawn - selected - not_selected - expired submittedAt: type: string format: date-time updatedAt: type: string format: date-time LotteryEntryView: type: object additionalProperties: false required: - id - state - submittedAt - updatedAt properties: id: type: string evidenceUrl: type: string state: type: string enum: - active - withdrawn submittedAt: type: string format: date-time updatedAt: type: string format: date-time Commitment: type: object additionalProperties: false required: - id - version - marketId - marketVersion - creatorPrincipalId - participantPrincipalId - state - terms - createdAt - updatedAt properties: id: type: string minLength: 1 version: type: integer format: uint64 minimum: 1 marketId: type: string minLength: 1 marketVersion: type: integer format: uint64 minimum: 1 creatorPrincipalId: type: string minLength: 1 participantPrincipalId: type: string minLength: 1 paymentAuthorizationId: type: string minLength: 1 settlementState: type: string enum: - pending - settled - failed settlementOperationId: type: string minLength: 1 settlementFailureCode: type: string minLength: 1 refundState: type: string enum: - pending - refunded - failed refundOperationId: type: string minLength: 1 refundFailureCode: type: string minLength: 1 state: type: string enum: - provisional - awaiting_confirmations - committed - declined - expired - failed terms: description: Immutable terms generated by the market mechanism. oneOf: - $ref: '#/components/schemas/DirectClaimCommitmentTerms' - $ref: '#/components/schemas/SealedAuctionCommitmentTerms' requiredConfirmationPrincipalIds: type: array items: type: string minLength: 1 confirmedPrincipalIds: type: array items: type: string minLength: 1 expiresAt: type: string format: date-time description: Confirmation deadline when the commitment is awaiting confirmation. createdAt: type: string format: date-time updatedAt: type: string format: date-time ErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: Human-readable detail. Clients should branch on code. MarketDiscoverability: type: string enum: - listed - unlisted default: listed description: >- Listed markets appear in public discovery. Unlisted markets remain readable by exact market ID and are not private. Subject: type: object additionalProperties: false required: - schema - data properties: schema: type: string minLength: 1 description: >- Versioned identifier chosen by the client for the subject data shape. example: restaurant-table.v1 data: type: object description: >- Client-defined JSON object describing the item, service, capacity, or right being allocated. additionalProperties: true example: partySize: 2 startsAt: '2026-09-19T19:00:00Z' FulfillmentSpec: type: object additionalProperties: false required: - requestSchema - acceptedDeliveryTransports - outputMediaTypes properties: requestSchema: type: string minLength: 1 description: Versioned schema required for participant requests. acceptedDeliveryTransports: type: array minItems: 1 uniqueItems: true items: type: string minLength: 1 providerEndpoint: $ref: '#/components/schemas/FulfillmentEndpoint' outputMediaTypes: type: array minItems: 1 uniqueItems: true items: type: string minLength: 3 slaSeconds: type: integer format: uint32 minimum: 1 description: Optional fulfillment target measured from commitment creation. MechanismSelection: description: >- Supported versioned allocation mechanism and its immutable configuration. oneOf: - $ref: '#/components/schemas/DirectClaimMechanism' - $ref: '#/components/schemas/SealedAuctionMechanism' - $ref: '#/components/schemas/RequestForOffersMechanism' - $ref: '#/components/schemas/LotteryMechanism' discriminator: propertyName: presetId mapping: direct-claim.v1: '#/components/schemas/DirectClaimMechanism' sealed-forward-auction.v1: '#/components/schemas/SealedAuctionMechanism' request-for-offers.v1: '#/components/schemas/RequestForOffersMechanism' lottery.v1: '#/components/schemas/LotteryMechanism' FundingPolicy: type: object additionalProperties: false required: - mode properties: mode: type: string enum: - none - reserve_on_submission acceptedRailIds: type: array items: type: string minLength: 1 description: Rails accepted for funded participation. settlementGraceSeconds: type: integer format: uint32 minimum: 0 description: >- Additional authorization lifetime required beyond the mechanism horizon. PaymentCredentialInstruction: type: object additionalProperties: false required: - railId - credentialType - credentialTarget properties: railId: type: string minLength: 1 credentialType: type: string minLength: 1 credentialTarget: type: string minLength: 1 DirectClaimCommitmentTerms: type: object additionalProperties: false required: - subject - pricing properties: subject: $ref: '#/components/schemas/Subject' pricing: $ref: '#/components/schemas/DirectClaimPricing' fulfillment: $ref: '#/components/schemas/FulfillmentTerms' SealedAuctionCommitmentTerms: type: object additionalProperties: false required: - subject - winningBidId - pricing properties: subject: $ref: '#/components/schemas/Subject' winningBidId: type: string minLength: 1 pricing: $ref: '#/components/schemas/SealedAuctionClearingPrice' ErrorCode: type: string enum: - invalid_request - unauthenticated - forbidden - identity_conflict - identity_not_found - invalid_credential - credential_conflict - signing_key_mismatch - delegation_not_found - delegation_conflict - delegation_inactive - not_found - method_not_allowed - idempotency_conflict - concurrent_update - internal_error - invalid_command - authority_reference_required - unknown_mechanism - invalid_mechanism_config - market_not_found - commitment_not_found - principal_not_authorized - version_conflict - invalid_market_transition - invalid_commitment_transition - actor_not_authorized - capacity_exhausted - invalid_payment_authorization - payment_authority_required - payment_mandate_exceeded - payment_rail_unavailable - payment_rail_unsupported FulfillmentEndpoint: type: object additionalProperties: false required: - transport - uri properties: transport: type: string minLength: 1 description: Lowercase transport identifier such as email, https, or a2a. uri: type: string format: uri description: >- Absolute contact or delivery URI. It must not contain credentials, secrets, or a fragment. DirectClaimMechanism: type: object additionalProperties: false required: - presetId - config properties: presetId: type: string const: direct-claim.v1 config: $ref: '#/components/schemas/DirectClaimConfig' SealedAuctionMechanism: type: object additionalProperties: false required: - presetId - config properties: presetId: type: string const: sealed-forward-auction.v1 config: $ref: '#/components/schemas/SealedAuctionConfig' RequestForOffersMechanism: type: object additionalProperties: false required: - presetId - config properties: presetId: type: string const: request-for-offers.v1 config: $ref: '#/components/schemas/RequestForOffersConfig' LotteryMechanism: type: object additionalProperties: false required: - presetId - config properties: presetId: type: string const: lottery.v1 config: oneOf: - $ref: '#/components/schemas/LotteryImmediateConfig' - $ref: '#/components/schemas/LotteryReviewedConfig' DirectClaimPricing: description: Free or posted terms recorded in the resulting commitment. oneOf: - $ref: '#/components/schemas/FreePricing' - $ref: '#/components/schemas/PostedPricing' discriminator: propertyName: mode mapping: free: '#/components/schemas/FreePricing' posted: '#/components/schemas/PostedPricing' FulfillmentTerms: type: object additionalProperties: false required: - spec - handoff properties: spec: $ref: '#/components/schemas/FulfillmentSpec' handoff: $ref: '#/components/schemas/FulfillmentHandoff' SealedAuctionClearingPrice: type: object additionalProperties: false required: - rule - amountMinor - currency properties: rule: type: string const: second_price amountMinor: type: integer format: int64 minimum: 0 description: >- Second-highest eligible bid or the reserve when higher. Zero is possible without a reserve and one bidder. currency: $ref: '#/components/schemas/Currency' DirectClaimConfig: description: Capacity, pricing, and confirmation rules for a direct-claim market. oneOf: - $ref: '#/components/schemas/DirectClaimImmediateConfig' - $ref: '#/components/schemas/DirectClaimHeldConfig' discriminator: propertyName: confirmation mapping: none: '#/components/schemas/DirectClaimImmediateConfig' creator: '#/components/schemas/DirectClaimHeldConfig' participant: '#/components/schemas/DirectClaimHeldConfig' both: '#/components/schemas/DirectClaimHeldConfig' SealedAuctionConfig: type: object additionalProperties: false required: - currency - closesAt - holdDurationSeconds properties: currency: $ref: '#/components/schemas/Currency' reserveAmountMinor: type: integer format: int64 minimum: 1 description: Optional positive reserve in minor currency units. closesAt: type: string format: date-time description: >- Fixed auction close. It must still be in the future when the draft is published. holdDurationSeconds: type: integer format: uint32 minimum: 1 description: Winner confirmation period after resolution. resolutionDeadline: type: string format: date-time description: >- Final promotion and resolution horizon, which must be after closesAt. Optional for unfunded auctions and required for funded ones, where funding must stay valid through it plus settlement grace. RequestForOffersConfig: type: object additionalProperties: false required: - capacity - offerSchema - offersCloseAt - selectionClosesAt - selectionTiming - pricing properties: capacity: type: integer format: uint32 minimum: 1 offerSchema: type: string minLength: 1 offersCloseAt: type: string format: date-time description: Must be after publication. selectionClosesAt: type: string format: date-time description: Must be after offersCloseAt. selectionTiming: type: string const: after_deadline pricing: $ref: '#/components/schemas/RequestForOffersPricing' LotteryImmediateConfig: type: object additionalProperties: false required: - capacity - entryClosesAt - confirmation properties: capacity: type: integer format: uint32 minimum: 1 entryClosesAt: type: string format: date-time description: >- Must follow publication; entries and withdrawals at or after it are rejected. confirmation: type: string const: none confirmationWindowSeconds: false resolutionDeadline: false eligibilityTerms: type: string maxLength: 8192 description: >- At most 8192 UTF-8 bytes; described qualifications are not automatically verified. Funding must be none. LotteryReviewedConfig: type: object additionalProperties: false required: - capacity - entryClosesAt - confirmation - confirmationWindowSeconds - resolutionDeadline properties: capacity: type: integer format: uint32 minimum: 1 entryClosesAt: type: string format: date-time description: Must follow publication. confirmation: type: string const: creator confirmationWindowSeconds: type: integer format: uint32 minimum: 1 description: >- Per-candidate review window from actual selection, capped at resolutionDeadline. Late selection or promotion can yield a shorter window, even nearly zero. resolutionDeadline: type: string format: date-time description: >- Must follow entryClosesAt; no awards or promotions after this deadline. eligibilityTerms: type: string maxLength: 8192 description: >- At most 8192 UTF-8 bytes; creator evaluates evidence for provisional winners. Funding must be none. FreePricing: type: object additionalProperties: false required: - mode properties: mode: type: string const: free PostedPricing: type: object additionalProperties: false required: - mode - amountMinor - currency properties: mode: type: string const: posted amountMinor: type: integer format: int64 minimum: 1 description: Positive posted amount in minor currency units. currency: $ref: '#/components/schemas/Currency' FulfillmentHandoff: type: object additionalProperties: false required: - request - deliveryEndpoint properties: request: $ref: '#/components/schemas/Subject' deliveryEndpoint: $ref: '#/components/schemas/FulfillmentEndpoint' Currency: type: string pattern: ^[A-Z]{3}$ description: Three-letter uppercase currency code. example: USD DirectClaimImmediateConfig: type: object additionalProperties: false required: - capacity - pricing - confirmation properties: capacity: type: integer format: uint32 minimum: 1 description: Number of successful commitments the market can allocate. pricing: $ref: '#/components/schemas/DirectClaimPricing' confirmation: type: string const: none holdDurationSeconds: type: integer format: uint32 maximum: 0 description: >- May be omitted. An explicit value must be 0 and is removed during normalization. maxPerPrincipal: type: integer format: uint32 minimum: 1 description: >- Optional cap on the live commitments one participant principal may hold. Declined, expired, and failed commitments release the allowance. Omit for no limit. claimsCloseAt: type: string format: date-time description: >- Optional RFC 3339 cutoff for accepting claims, which must be after publication. Claims at or after it are rejected and the market closes automatically. DirectClaimHeldConfig: type: object additionalProperties: false required: - capacity - pricing - confirmation - holdDurationSeconds properties: capacity: type: integer format: uint32 minimum: 1 description: Number of successful commitments the market can allocate. pricing: $ref: '#/components/schemas/DirectClaimPricing' confirmation: type: string enum: - creator - participant - both description: Principals that must confirm before the commitment is final. holdDurationSeconds: type: integer format: uint32 minimum: 1 description: Confirmation period before the commitment expires. maxPerPrincipal: type: integer format: uint32 minimum: 1 description: >- Optional cap on the live commitments one participant principal may hold. Declined, expired, and failed commitments release the allowance. Omit for no limit. claimsCloseAt: type: string format: date-time description: >- Optional RFC 3339 cutoff for accepting claims, which must be after publication. Claims at or after it are rejected and the market closes automatically. RequestForOffersPricing: type: object additionalProperties: false required: - mode properties: mode: type: string enum: - none - optional - required currency: $ref: '#/components/schemas/Currency' maximumAmountMinor: type: integer format: int64 minimum: 1 description: >- None forbids currency and maximum; optional or required need one currency. responses: Unauthorized: description: Request authentication failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthenticated message: request authentication failed Forbidden: description: The actor or principal is not authorized for this action. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: The requested market, commitment, or route was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalError: description: The command could not be completed because of an internal failure. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: AmbientActor: type: apiKey in: header name: X-Ambient-Actor description: Provisioned actor identifier. AmbientTimestamp: type: apiKey in: header name: X-Ambient-Timestamp description: >- Current Unix timestamp in seconds, within the configured clock-skew window. AmbientSignature: type: apiKey in: header name: Authorization description: | Ambient-HMAC followed by a space and the unpadded base64url HMAC-SHA256 signature. See Authentication and authority for the canonical input. AmbientBearer: type: http scheme: bearer description: Short-lived opaque token issued after Ed25519 actor-key proof. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.