La bolsa

Los vendedores publican demandas (lo mínimo que aceptarán por unidad-minuto); los compradores publican ofertas (lo máximo que pagarán). Cuando una oferta coincide con una demanda, operan al precio de la orden en espera por la cantidad emparejada. Una operación liquidada contra el listado de flota de un vendedor se convierte en un arrendamiento canjeable a ese precio.

# Post a bid (buyer) or ask (seller) on a fungible class.
curl https://api.commandagi.com/market/vm.gpu-l4/orders \
  -H "Authorization: Bearer $COMMANDAGI_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "side": "bid", "price": 24, "qty": 1 }'   # ≤ 24 credits/min

GET /market/:resourceClass devuelve el libro en vivo (mejor oferta/demanda, spread, profundidad), la cinta de operaciones recientes, un gráfico de precio continuo, y las señales de demanda actuales — todo lo que renderiza la terminal. La terminal web en /market/class/<resourceClass> la consulta en vivo.

{
  "book": { "bestBid": 20, "bestAsk": 25, "spread": 5, "bidDepth": […], "askDepth": […] },
  "tape": [ { "price": 22, "qty": 1, "createdAt": … } ],
  "signals": { "utilization": 0.82, "queueDepth": 3, "totalSlots": 4 }
}

Cualquier orden puede llevar un pin geo — { lat, lng, radiusM? }. Una oferta y una demanda solo cruzan cuando cada pin cae dentro del radio del otro (un radio omitido significa «en cualquier lugar»). Así es como una oferta en espera anclada a Times Square se llena solo contra proveedores físicamente cercanos, y cómo un proveedor itinerante solo ve trabajos dentro de su radio de servicio. Las ofertas también pueden adjuntar una pista de job (label, estMinutes, setupCost, switchCost) que los compradores muestran a los proveedores y que el emparejador usa para fijar el precio.

Del lado de la demanda, un vendedor fija un solo control deslizante de convenience (0→1): 0 toma todo a su precio de demanda para maximizar ganancias, 1 significa menos interrupciones — el emparejador recarga los trabajos cortos, con mucha preparación, o lejanos, así que un vendedor inclinado a la conveniencia queda automáticamente fuera de precio de la molestia. El control deslizante único se mapea del lado del servidor a coeficientes. Las demandas también pueden fijar supplyKind (machine o human) y una expiración ttlSeconds.

Los proveedores registran su disponibilidad con POST /me/presence (estado en línea, ubicación, radio de servicio, las clases que atienden, y si quieren ser notificados), descubren trabajo vía GET /jobs/nearby, y aceptan con un toque una oferta localizada con POST /market/:resourceClass/orders/:orderId/accept. Los tokens de notificaciones push registrados en /me/push-tokens nos permiten despertar a un proveedor cercano en el instante en que aparece un trabajo compatible.

# A located bid: only fills against supply physically within range.
curl https://api.commandagi.com/market/robot.humanoid/orders \
  -H "Authorization: Bearer $COMMANDAGI_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "side": "bid", "price": 60, "qty": 1,
    "geo": { "lat": 40.7580, "lng": -73.9855, "radiusM": 300 },
    "job": { "label": "Record in Times Square", "estMinutes": 20, "setupCost": 50 }
  }'

# A convenience-leaning ask: the matcher surcharges hassle jobs so you
# auto-price out of short / high-setup / far work. One 0→1 slider is enough.
curl https://api.commandagi.com/market/robot.humanoid/orders \
  -H "Authorization: Bearer $COMMANDAGI_API_KEY" \
  -d '{ "side": "ask", "price": 40, "convenience": 0.8, "supplyKind": "human" }'

# Suppliers go online, then accept located bids nearby.
curl "https://api.commandagi.com/jobs/nearby?lat=40.7580&lng=-73.9855&radiusM=1000&class=robot.humanoid"
curl -X POST https://api.commandagi.com/market/robot.humanoid/orders/<id>/accept \
  -d '{}'

Los vendedores que no quieren un libro de órdenes pueden usar en su lugar un modelo de precio dynamic: una tarifa base que flota con la utilización en vivo y la profundidad de cola, acotada a un mínimo/máximo. Las mismas señales de demanda, más simple de publicar.