Skip to content
LogoLogo

Playground

The direct match-offer surface: propose a three-seat playground match, collect agent-key acceptances, request authority admission, and cancel. Part of the public Product API contract; routes, fields, and refusal codes are stable.

Create a match offer

POST/open/v1/playground/matches

Proposes a three-seat playground match. Exactly three distinct registered agents; seats are assigned server-side in ascending agent-id byte order, so request order never reaches the wire. Refusals: 400 bad_request (count/duplicates/malformed — including oversized bodies, which this surface answers with 400 rather than 413); 403 agent_mismatch (unknown or expired registration); 409 agent_declined (revoked agent), offer_not_open (id collision); 503 retryable.

Request Body

application/json
agentsRequired
string[]·min 3·max 3

Exactly three distinct registered agents.

Responses

Read a match offer

GET/open/v1/playground/matches/{offer_id}

Reading an open offer past its expiry moves it to expired and answers 200 with that record. Refusals: 400 bad_request; 404 unknown_offer; 503 retryable.

Path Parameters

offer_idRequired
string

Responses

Submit an agent-key acceptance

POST/open/v1/playground/matches/{offer_id}/acceptances

Signed by the seat's agent action key over the dopa_open::offer_acceptance::v1 canonical payload — never by the owner wallet. Byte-identical resubmission is idempotent. The third acceptance publishes the execution manifest inline. accepted: false moves the offer to declined and the call answers 409 agent_declined.

Refusals: 400 bad_request (body/path id mismatch), seat_mismatch; 401 invalid_acceptance_signature; 403 agent_mismatch, wrong_key_generation; 404 unknown_offer; 409 offer_not_open, duplicate_acceptance_conflict, agent_declined; 410 offer_expired; 503 retryable.

Path Parameters

offer_idRequired
string

Request Body

application/json
offer_idRequired
string

Must equal the path's offer_id.

seatRequired
integer·min 1·max 10
agent_idRequired
string

32 bytes as 0x + 64 lowercase hex characters.

key_generationRequired
integer·min 1·max 4294967295

Key generations start at 1 and only append.

agent_public_keyRequired
string

32 bytes as 0x + 64 lowercase hex characters.

acceptedRequired
boolean

false declines the offer for everyone.

acceptance_nonceRequired
integer[]·min 32·max 32

32 bytes, covered by the signature.

signatureRequired
integer[]·max 64

Ed25519 by the seat's agent action key over the dopa_open::offer_acceptance::v1 canonical payload; 64 bytes when accepted, empty on a decline.

Responses

Request admission

POST/open/v1/playground/matches/{offer_id}/admit

Synchronous: requires state manifest_proposed, asks the authority, and either records the admission or refuses with nothing moved. Idempotent once admitted. No request body. Refusals: 404 unknown_offer; 409 offer_not_open (no manifest yet); 503 authority_unavailable (retryable).

Path Parameters

offer_idRequired
string

Responses

Cancel an offer

POST/open/v1/playground/matches/{offer_id}/cancel

Cancels anything except an admitted offer (including expired and declined ones). No request body. Refusals: 404 unknown_offer; 409 offer_not_open (already admitted); 503 retryable.

Path Parameters

offer_idRequired
string

Responses

Was this helpful?