Ordens
O namespace orders de @getenginex/sdk-predictions coloca, lista, cancela e altera ordens. Todos os métodos exigem login: sem sessão, rejeitam com UNAUTHENTICATED antes de qualquer request.
Veja uma ordem sendo enviada, com a Idempotency-Key e o livro mudando ao vivo, na demo de Orderbook ao vivo.
Preço, quantidade e enums
- Preço: inteiro em centavos. Numa ordem limitada (o padrão) o
priceé obrigatório, de 1 a 99. Numa ordem a mercado opriceé opcional: omitido, o SDK manda0(é o que o app player envia); informado, é um inteiro de 0 a 99. Quantidade: inteiro de contratos, maior que zero. O gateway não valida nada disso, então o SDK rejeita valores fora das regras comCONFIGURATION_ERROR, sem request (limitada comprice: 0ou semprice,100,60.5, ouquantity: 0,1.5). postOnlyereduceOnly, quando informados, precisam ser booleanos.sideé'yes' | 'no',directioné'buy' | 'sell',orderTypeé'limit' | 'market'(padrãolimit) etimeInForceé'gtc' | 'ioc' | 'fok'(padrãogtc). Um valor fora desses também rejeita antes do request: o gateway trataria umorderTypedesconhecido comolimit, e uma ordem diferente da pedida custa dinheiro.- Na resposta,
statusépending,open,partial,filled,canceled,expiredourejected, em minúsculas e sem o prefixo do protobuf, iguais no REST e no realtime.
Colocar uma ordem
// Limit order: stays in the book until it executes or is canceled
const order = await predictions.orders.place({
marketId: 'mkt-1',
side: 'yes',
direction: 'buy',
price: 60, // 60 cents per contract
quantity: 10,
})
// Market order: executes whatever is in the book right away, with no price (the SDK sends price: 0)
await predictions.orders.place({
marketId: 'mkt-1',
side: 'yes',
direction: 'buy',
orderType: 'market',
timeInForce: 'ioc',
quantity: 5,
})O tipo PlaceOrderInput é uma união discriminada por orderType: o price é obrigatório na limitada e opcional na a mercado. Um price diferente de zero numa ordem a mercado não é um teto garantido pelo SDK: quem o interpreta é o serviço de predictions, e o app player de produção sempre manda 0. Use-o só se souber o que ele faz.
place devolve a Order (o gateway responde HTTP 200). postOnly: true rejeita a ordem se ela cruzaria o spread; reduceOnly: true só permite reduzir uma posição existente.
Idempotência e retry
place movimenta dinheiro, então é idempotente. A mesma chave vai no header Idempotency-Key e no campo idempotency_key do corpo (o gateway aceita as duas), e é a mesma na nova tentativa que o SDK faz sozinho depois de renovar a sessão (401). Sem options.idempotencyKey, o SDK gera uma chave por chamada.
Isso protege a renovação de sessão, mas não um erro de rede: se a chamada falhar com NETWORK_ERROR ou TIMEOUT, a ordem pode ou não ter chegado ao gateway. Para repetir sem duplicar, gere a chave uma vez por intenção do jogador (um clique em "Comprar"), guarde-a e passe a mesma em cada tentativa. Espaços nas pontas da chave são aparados, e o mesmo texto vai no header e no corpo:
const key = crypto.randomUUID() // one per click, not one per attempt
const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
async function buy() {
for (let attempt = 0; ; attempt++) {
try {
return await predictions.orders.place(input, { idempotencyKey: key }) // same key: no duplicate order
} catch (error) {
const retryable =
isEnginexError(error, 'NETWORK_ERROR') || isEnginexError(error, 'TIMEOUT') || isEnginexError(error, 'KEY_IN_USE')
if (!retryable || attempt === 3) throw error
await wait(500 * 2 ** attempt) // wait before retrying (see KEY_IN_USE below)
}
}
}O gateway guarda a chave e protege contra repetição por dois erros, que chegam com o code (o SDK os entrega mesmo vindo no formato cru do middleware):
KEY_IN_USE(HTTP 409): a primeira chamada com essa chave ainda está sendo processada. Espere (com backoff, como acima) e repita com a mesma chave; não gere outra, ou a ordem pode sair duas vezes.PAYLOAD_MISMATCH(HTTP 422): a mesma chave foi usada com outra ordem (outro mercado, preço ou quantidade). Cada intenção diferente precisa de uma chave nova. (INVALID_KEY, HTTP 400, é uma chave fora do formato aceito.)
Em origem insegura (http://, sem crypto.randomUUID), o SDK gera a chave com crypto.getRandomValues. Sem Web Crypto nenhum, ele não consegue gerar a chave e rejeita com CONFIGURATION_ERROR: passe a sua idempotencyKey.
Uma chave nova é uma ordem nova. Uma chave vazia ('') conta como ausente e o SDK gera outra.
Lote
const results = await predictions.orders.placeBatch({
orders: [
{ marketId: 'mkt-1', side: 'yes', direction: 'buy', price: 60, quantity: 10 },
{ marketId: 'mkt-2', side: 'no', direction: 'buy', price: 30, quantity: 5 },
],
})
for (const result of results) {
if (result.success) console.log(result.index, result.order.id)
else console.warn(result.index, result.error.message)
}- O lote não é atômico: cada ordem dá certo ou falha sozinha, e um
saldo insuficientena segunda não desfaz a primeira. O resultado vem porindex(a posição na lista enviada), já em ordem, e as falhas não viram exceção. O gateway devolve só a mensagem do erro, entãoerror.codeficaundefined. - A rota do lote não passa pelo middleware de idempotência do gateway: não há header
Idempotency-Keyeoptions.idempotencyKeyé ignorada. Cada ordem leva umaidempotency_keydistinta no corpo: aidempotencyKeyque você passar na ordem (aparada; repetida no mesmo lote éCONFIGURATION_ERROR) ou uma gerada pelo SDK, nova a cada chamada. - Para repetir um lote com segurança depois de um erro de rede, guarde as chaves e reenvie as mesmas em cada ordem (
{ ...order, idempotencyKey: 'batch-7-a' }). Sem chaves suas, não repita às cegas: as ordens do primeiro envio podem ter entrado; confiraorders.list()antes. - Nas mutations (
createPredictionsMutations,useEnginexMutations), o SDK faz isso por você: as chaves ficam guardadas por resultado decreatePredictionsMutationsdepois de uma falha ambígua (rede, timeout, 5xx,KEY_IN_USEouVALIDATION_ERRORdepois de 2xx) ou de um sucesso parcial, e são reaproveitadas enquanto o conteúdo do lote for o mesmo. Sucesso total, erro não ambíguo ou lote diferente geram chaves novas. Veja React. - A resposta é validada em modo
strict: precisa trazer os índices0..n-1uma vez cada e aorderem cada sucesso; senão a chamada rejeita comVALIDATION_ERROR. - Uma lista vazia ou com uma ordem inválida rejeita com
CONFIGURATION_ERRORantes do request: nenhuma ordem sai.
Listar, buscar, cancelar e alterar
const orders = await predictions.orders.list() // fixed first page of 50; no filters or pagination
const one = await predictions.orders.get({ orderId: order.id })
const canceled = await predictions.orders.cancel({ orderId: order.id }) // status 'canceled'
const amended = await predictions.orders.amend({ orderId: order.id, newPrice: 55, newQuantity: 8 })amend recebe newPrice e/ou newQuantity (sem nenhum dos dois, CONFIGURATION_ERROR sem request) e devolve a ordem atualizada. O gateway implementa como cancelar e recolocar, então use a ordem devolvida (o id e a posição na fila podem mudar). amend não é idempotente: não envia chave, e repeti-lo depois de um erro de rede pode alterar duas vezes. Confira o estado com get antes.
Um orderId vazio, com espaço no início ou no fim, com /, . ou .. rejeita com CONFIGURATION_ERROR antes do request. O mesmo vale para o marketId de place/placeBatch.
Erros
Decida sempre pelo code, não pelo status HTTP: vários códigos de predictions chegam como HTTP 500 porque o gateway não os mapeia (MARKET_NOT_FOUND, MARKET_NOT_OPEN, ORDER_NOT_FOUND, NO_LIQUIDITY).
try {
await predictions.orders.place(input, { idempotencyKey: key })
} catch (error) {
if (isEnginexError(error, 'INSUFFICIENT_BALANCE')) showDeposit()
else if (isEnginexError(error, 'NO_LIQUIDITY')) notify('No offers at this price')
else if (isEnginexError(error, 'MARKET_NOT_OPEN')) notify('Market closed')
else throw error
}Testes
withPredictionsRoutes() inclui as rotas de ordens (faça login no mock antes: sem token elas respondem 401):
placedevolve uma ordemopen(colateral reservado); comorderType: 'market'ela executa na hora e vira posição. A mesma chave de idempotência devolve a mesma ordem, sem criar outra.- Uma ordem a mercado sem
priceexecuta ao último preço do lado, e opriceda ordem fica0. placeBatchcoloca cada ordem sozinha: ummarketIddesconhecido falha aquela ordem (success: false) e as demais seguem.- Um mercado desconhecido dá
MARKET_NOT_FOUNDe uma ordem desconhecida,ORDER_NOT_FOUND, ambos com HTTP 500, como o gateway. Para simularNO_LIQUIDITYouINSUFFICIENT_BALANCE, sobrescreva a rota:
import { fail } from '@getenginex/sdk/testing'
createMockFetch(
withPredictionsRoutes({
routes: { 'POST /api/v1/predictions/orders': () => fail(500, 'NO_LIQUIDITY', 'no liquidity') },
}),
)