Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

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 o price é opcional: omitido, o SDK manda 0 (é 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 com CONFIGURATION_ERROR, sem request (limitada com price: 0 ou sem price, 100, 60.5, ou quantity: 0, 1.5).
  • postOnly e reduceOnly, quando informados, precisam ser booleanos.
  • side é 'yes' | 'no', direction é 'buy' | 'sell', orderType é 'limit' | 'market' (padrão limit) e timeInForce é 'gtc' | 'ioc' | 'fok' (padrão gtc). Um valor fora desses também rejeita antes do request: o gateway trataria um orderType desconhecido como limit, e uma ordem diferente da pedida custa dinheiro.
  • Na resposta, status é pending, open, partial, filled, canceled, expired ou rejected, em minúsculas e sem o prefixo do protobuf, iguais no REST e no realtime.

Colocar uma ordem ​

ts
// 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:

ts
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 ​

ts
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 insuficiente na segunda não desfaz a primeira. O resultado vem por index (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ão error.code fica undefined.
  • A rota do lote não passa pelo middleware de idempotência do gateway: não há header Idempotency-Key e options.idempotencyKey é ignorada. Cada ordem leva uma idempotency_key distinta no corpo: a idempotencyKey que 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; confira orders.list() antes.
  • Nas mutations (createPredictionsMutations, useEnginexMutations), o SDK faz isso por você: as chaves ficam guardadas por resultado de createPredictionsMutations depois de uma falha ambígua (rede, timeout, 5xx, KEY_IN_USE ou VALIDATION_ERROR depois 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 índices 0..n-1 uma vez cada e a order em cada sucesso; senão a chamada rejeita com VALIDATION_ERROR.
  • Uma lista vazia ou com uma ordem inválida rejeita com CONFIGURATION_ERROR antes do request: nenhuma ordem sai.

Listar, buscar, cancelar e alterar ​

ts
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).

ts
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):

  • place devolve uma ordem open (colateral reservado); com orderType: '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 price executa ao último preço do lado, e o price da ordem fica 0.
  • placeBatch coloca cada ordem sozinha: um marketId desconhecido falha aquela ordem (success: false) e as demais seguem.
  • Um mercado desconhecido dá MARKET_NOT_FOUND e uma ordem desconhecida, ORDER_NOT_FOUND, ambos com HTTP 500, como o gateway. Para simular NO_LIQUIDITY ou INSUFFICIENT_BALANCE, sobrescreva a rota:
ts
import { fail } from '@getenginex/sdk/testing'

createMockFetch(
  withPredictionsRoutes({
    routes: { 'POST /api/v1/predictions/orders': () => fail(500, 'NO_LIQUIDITY', 'no liquidity') },
  }),
)