Submit a direct claim
curl --request POST \
--url https://{host}/v1/markets/{marketId}/direct-claims \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'X-Ambient-Actor: <api-key>' \
--header 'X-Ambient-Timestamp: <api-key>' \
--data '
{
"commandId": "table-claim-1",
"principalId": "diner-1"
}
'import requests
url = "https://{host}/v1/markets/{marketId}/direct-claims"
payload = {
"commandId": "table-claim-1",
"principalId": "diner-1"
}
headers = {
"X-Ambient-Actor": "<api-key>",
"X-Ambient-Timestamp": "<api-key>",
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Ambient-Actor': '<api-key>',
'X-Ambient-Timestamp': '<api-key>',
Authorization: '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({commandId: 'table-claim-1', principalId: 'diner-1'})
};
fetch('https://{host}/v1/markets/{marketId}/direct-claims', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{host}/v1/markets/{marketId}/direct-claims",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'commandId' => 'table-claim-1',
'principalId' => 'diner-1'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json",
"X-Ambient-Actor: <api-key>",
"X-Ambient-Timestamp: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{host}/v1/markets/{marketId}/direct-claims"
payload := strings.NewReader("{\n \"commandId\": \"table-claim-1\",\n \"principalId\": \"diner-1\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Ambient-Actor", "<api-key>")
req.Header.Add("X-Ambient-Timestamp", "<api-key>")
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{host}/v1/markets/{marketId}/direct-claims")
.header("X-Ambient-Actor", "<api-key>")
.header("X-Ambient-Timestamp", "<api-key>")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"commandId\": \"table-claim-1\",\n \"principalId\": \"diner-1\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{host}/v1/markets/{marketId}/direct-claims")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Ambient-Actor"] = '<api-key>'
request["X-Ambient-Timestamp"] = '<api-key>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"commandId\": \"table-claim-1\",\n \"principalId\": \"diner-1\"\n}"
response = http.request(request)
puts response.read_body{
"market": {
"id": "<string>",
"version": 2,
"state": "draft",
"discoverability": "listed",
"creator": {
"principalId": "<string>",
"actorId": "<string>",
"authorityRef": "<string>"
},
"subject": {
"schema": "restaurant-table.v1",
"data": {
"partySize": 2,
"startsAt": "2026-09-19T19:00:00Z"
}
},
"mechanism": {
"presetId": "direct-claim.v1",
"config": {
"capacity": 2,
"pricing": {
"mode": "free"
},
"confirmation": "none",
"holdDurationSeconds": -1,
"maxPerPrincipal": 2,
"claimsCloseAt": "2023-11-07T05:31:56Z"
}
},
"mechanismState": {
"allocated": 1
},
"funding": {
"mode": "none",
"acceptedRailIds": [
"<string>"
],
"settlementGraceSeconds": 1
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"externalRef": "<string>",
"fulfillment": {
"requestSchema": "<string>",
"acceptedDeliveryTransports": [
"<string>"
],
"outputMediaTypes": [
"<string>"
],
"providerEndpoint": {
"transport": "<string>",
"uri": "<string>"
},
"slaSeconds": 2
},
"publicationCredentialId": "<string>"
},
"commitments": [
{
"id": "<string>",
"version": 2,
"marketId": "<string>",
"marketVersion": 2,
"creatorPrincipalId": "<string>",
"participantPrincipalId": "<string>",
"state": "provisional",
"terms": {
"subject": {
"schema": "restaurant-table.v1",
"data": {
"partySize": 2,
"startsAt": "2026-09-19T19:00:00Z"
}
},
"pricing": {
"mode": "free"
},
"fulfillment": {
"spec": {
"requestSchema": "<string>",
"acceptedDeliveryTransports": [
"<string>"
],
"outputMediaTypes": [
"<string>"
],
"providerEndpoint": {
"transport": "<string>",
"uri": "<string>"
},
"slaSeconds": 2
},
"handoff": {
"request": {
"schema": "restaurant-table.v1",
"data": {
"partySize": 2,
"startsAt": "2026-09-19T19:00:00Z"
}
},
"deliveryEndpoint": {
"transport": "<string>",
"uri": "<string>"
}
}
}
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"paymentAuthorizationId": "<string>",
"settlementState": "pending",
"settlementOperationId": "<string>",
"settlementFailureCode": "<string>",
"refundState": "pending",
"refundOperationId": "<string>",
"refundFailureCode": "<string>",
"requiredConfirmationPrincipalIds": [
"<string>"
],
"confirmedPrincipalIds": [
"<string>"
],
"expiresAt": "2023-11-07T05:31:56Z"
}
],
"events": [
{
"id": "<string>",
"type": "market.draft_created",
"marketId": "<string>",
"marketVersion": 2,
"commandId": "<string>",
"principalId": "<string>",
"actorId": "<string>",
"occurredAt": "2023-11-07T05:31:56Z",
"data": {
"discoverability": "listed",
"creator": {
"principalId": "<string>",
"actorId": "<string>",
"authorityRef": "<string>"
},
"subject": {
"schema": "restaurant-table.v1",
"data": {
"partySize": 2,
"startsAt": "2026-09-19T19:00:00Z"
}
},
"mechanism": {
"presetId": "direct-claim.v1",
"config": {
"capacity": 2,
"pricing": {
"mode": "free"
},
"confirmation": "none",
"holdDurationSeconds": -1,
"maxPerPrincipal": 2,
"claimsCloseAt": "2023-11-07T05:31:56Z"
}
},
"mechanismState": {
"allocated": 1
},
"fulfillment": {
"requestSchema": "<string>",
"acceptedDeliveryTransports": [
"<string>"
],
"outputMediaTypes": [
"<string>"
],
"providerEndpoint": {
"transport": "<string>",
"uri": "<string>"
},
"slaSeconds": 2
}
},
"sequence": 2,
"authorityRef": "<string>"
}
],
"bidReceipts": [
{
"bidId": "<string>",
"marketId": "<string>",
"marketVersion": 2,
"state": "active",
"submittedAt": "2023-11-07T05:31:56Z"
}
],
"auctionResolution": {
"outcome": "no_trade"
},
"offerReceipts": [
{
"offerId": "<string>",
"marketId": "<string>",
"marketVersion": 123,
"state": "active",
"submittedAt": "2023-11-07T05:31:56Z"
}
],
"requestForOffersResolution": {
"outcome": "offers_selected",
"selectedOfferIds": [
"<string>"
]
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "request authentication failed"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}Participation
Submit a direct claim
Claims capacity in an open direct-claim.v1 market. Omit expectedVersion to let Ambient order competing claims by authoritative server arrival.
POST
/
v1
/
markets
/
{marketId}
/
direct-claims
Submit a direct claim
curl --request POST \
--url https://{host}/v1/markets/{marketId}/direct-claims \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'X-Ambient-Actor: <api-key>' \
--header 'X-Ambient-Timestamp: <api-key>' \
--data '
{
"commandId": "table-claim-1",
"principalId": "diner-1"
}
'import requests
url = "https://{host}/v1/markets/{marketId}/direct-claims"
payload = {
"commandId": "table-claim-1",
"principalId": "diner-1"
}
headers = {
"X-Ambient-Actor": "<api-key>",
"X-Ambient-Timestamp": "<api-key>",
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Ambient-Actor': '<api-key>',
'X-Ambient-Timestamp': '<api-key>',
Authorization: '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({commandId: 'table-claim-1', principalId: 'diner-1'})
};
fetch('https://{host}/v1/markets/{marketId}/direct-claims', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{host}/v1/markets/{marketId}/direct-claims",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'commandId' => 'table-claim-1',
'principalId' => 'diner-1'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json",
"X-Ambient-Actor: <api-key>",
"X-Ambient-Timestamp: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{host}/v1/markets/{marketId}/direct-claims"
payload := strings.NewReader("{\n \"commandId\": \"table-claim-1\",\n \"principalId\": \"diner-1\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Ambient-Actor", "<api-key>")
req.Header.Add("X-Ambient-Timestamp", "<api-key>")
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{host}/v1/markets/{marketId}/direct-claims")
.header("X-Ambient-Actor", "<api-key>")
.header("X-Ambient-Timestamp", "<api-key>")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"commandId\": \"table-claim-1\",\n \"principalId\": \"diner-1\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{host}/v1/markets/{marketId}/direct-claims")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Ambient-Actor"] = '<api-key>'
request["X-Ambient-Timestamp"] = '<api-key>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"commandId\": \"table-claim-1\",\n \"principalId\": \"diner-1\"\n}"
response = http.request(request)
puts response.read_body{
"market": {
"id": "<string>",
"version": 2,
"state": "draft",
"discoverability": "listed",
"creator": {
"principalId": "<string>",
"actorId": "<string>",
"authorityRef": "<string>"
},
"subject": {
"schema": "restaurant-table.v1",
"data": {
"partySize": 2,
"startsAt": "2026-09-19T19:00:00Z"
}
},
"mechanism": {
"presetId": "direct-claim.v1",
"config": {
"capacity": 2,
"pricing": {
"mode": "free"
},
"confirmation": "none",
"holdDurationSeconds": -1,
"maxPerPrincipal": 2,
"claimsCloseAt": "2023-11-07T05:31:56Z"
}
},
"mechanismState": {
"allocated": 1
},
"funding": {
"mode": "none",
"acceptedRailIds": [
"<string>"
],
"settlementGraceSeconds": 1
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"externalRef": "<string>",
"fulfillment": {
"requestSchema": "<string>",
"acceptedDeliveryTransports": [
"<string>"
],
"outputMediaTypes": [
"<string>"
],
"providerEndpoint": {
"transport": "<string>",
"uri": "<string>"
},
"slaSeconds": 2
},
"publicationCredentialId": "<string>"
},
"commitments": [
{
"id": "<string>",
"version": 2,
"marketId": "<string>",
"marketVersion": 2,
"creatorPrincipalId": "<string>",
"participantPrincipalId": "<string>",
"state": "provisional",
"terms": {
"subject": {
"schema": "restaurant-table.v1",
"data": {
"partySize": 2,
"startsAt": "2026-09-19T19:00:00Z"
}
},
"pricing": {
"mode": "free"
},
"fulfillment": {
"spec": {
"requestSchema": "<string>",
"acceptedDeliveryTransports": [
"<string>"
],
"outputMediaTypes": [
"<string>"
],
"providerEndpoint": {
"transport": "<string>",
"uri": "<string>"
},
"slaSeconds": 2
},
"handoff": {
"request": {
"schema": "restaurant-table.v1",
"data": {
"partySize": 2,
"startsAt": "2026-09-19T19:00:00Z"
}
},
"deliveryEndpoint": {
"transport": "<string>",
"uri": "<string>"
}
}
}
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"paymentAuthorizationId": "<string>",
"settlementState": "pending",
"settlementOperationId": "<string>",
"settlementFailureCode": "<string>",
"refundState": "pending",
"refundOperationId": "<string>",
"refundFailureCode": "<string>",
"requiredConfirmationPrincipalIds": [
"<string>"
],
"confirmedPrincipalIds": [
"<string>"
],
"expiresAt": "2023-11-07T05:31:56Z"
}
],
"events": [
{
"id": "<string>",
"type": "market.draft_created",
"marketId": "<string>",
"marketVersion": 2,
"commandId": "<string>",
"principalId": "<string>",
"actorId": "<string>",
"occurredAt": "2023-11-07T05:31:56Z",
"data": {
"discoverability": "listed",
"creator": {
"principalId": "<string>",
"actorId": "<string>",
"authorityRef": "<string>"
},
"subject": {
"schema": "restaurant-table.v1",
"data": {
"partySize": 2,
"startsAt": "2026-09-19T19:00:00Z"
}
},
"mechanism": {
"presetId": "direct-claim.v1",
"config": {
"capacity": 2,
"pricing": {
"mode": "free"
},
"confirmation": "none",
"holdDurationSeconds": -1,
"maxPerPrincipal": 2,
"claimsCloseAt": "2023-11-07T05:31:56Z"
}
},
"mechanismState": {
"allocated": 1
},
"fulfillment": {
"requestSchema": "<string>",
"acceptedDeliveryTransports": [
"<string>"
],
"outputMediaTypes": [
"<string>"
],
"providerEndpoint": {
"transport": "<string>",
"uri": "<string>"
},
"slaSeconds": 2
}
},
"sequence": 2,
"authorityRef": "<string>"
}
],
"bidReceipts": [
{
"bidId": "<string>",
"marketId": "<string>",
"marketVersion": 2,
"state": "active",
"submittedAt": "2023-11-07T05:31:56Z"
}
],
"auctionResolution": {
"outcome": "no_trade"
},
"offerReceipts": [
{
"offerId": "<string>",
"marketId": "<string>",
"marketVersion": 123,
"state": "active",
"submittedAt": "2023-11-07T05:31:56Z"
}
],
"requestForOffersResolution": {
"outcome": "offers_selected",
"selectedOfferIds": [
"<string>"
]
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "request authentication failed"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}Authorizations
AmbientActor & AmbientTimestamp & AmbientSignatureAmbientBearer
Provisioned actor identifier.
Current Unix timestamp in seconds, within the configured clock-skew window.
Ambient-HMAC followed by a space and the unpadded base64url HMAC-SHA256 signature. See Authentication and authority for the canonical input.
Path Parameters
Client-selected market identifier.
Minimum string length:
1Body
application/json
Actor-scoped idempotency key. Retry the identical command with the same value.
Minimum string length:
1Principal represented by the authenticated actor.
Minimum string length:
1Optional optimistic version check. Omit or send 0 for server arrival order.
Required range:
x >= 0Required delegation identifier when the actor and principal differ. Omit for self-action.
Minimum string length:
1Required when the market uses reserve_on_submission funding.
Minimum string length:
1Show child attributes
Show child attributes
Response
Claim accepted.
Show child attributes
Show child attributes
Commitments created or changed by the command.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Amount-free receipts returned after accepted sealed bids.
Show child attributes
Show child attributes
Public result produced at close or after deterministic winner promotion.
- Option 1
- Option 2
Show child attributes
Show child attributes
Public-safe receipts returned after offer submission.
Show child attributes
Show child attributes
Show child attributes
Show child attributes