Scripts

Objetivo:

Permitir que o usuário do Tryd (“Usuário”) crie colunas para os Monitores de Cotações, indicadores para os gráficos e alertas e estratégias para envio de ordens ou avaliação do mercado.

Pré-requisitos:

Para facilitar o entendimento dos recursos implementados, os usuários devem ter conhecimento avançado:

•de pelo menos uma linguagem de script/programação (ex. JavaScript ou Java);

•dos mercados negociados na BVMF; e

•de análise técnica.

Responsabilidade:

O Usuário declara ter conhecimento de que o uso correto dos recursos disponibilizados é de sua inteira e única responsabilidade, bem como todas as decisões tomadas com base em informações geradas ou ordens enviadas pelos scripts do Usuário, não cabendo qualquer responsabilização da CellBroker pelo uso inadequado ou irregular dos recursos em questão.

O Usuário também declara ter total conhecimento de que a criação dos scripts, bem como de seus resultados são de sua inteira responsabilidade, como também são de sua responsabilidade o funcionamento do seu computador e o acesso à internet. A Cellbroker ressalta que o seu mau funcionamento pode interferir de forma negativa no funcionamento dos scripts, não podendo ser atribuída, pelo Usuário à CellBroker, qualquer falha decorrente de eventuais falhas.

O Usuário declara ainda ter conhecimento e concorda que: (i) deverá manter os requisitos mínimos necessários para o bom funcionamento do seu computador e que o Sistema Operacional, Excel, Antivirus, Firewall e outros softwares existentes na máquina do Usuário devem estar devidamente licenciados e atualizados; (ii) o acesso à máquina do Usuário deve ser restrito; e (iii) a responsabilidade deste ambiente estar livre de vírus e/ou de qualquer outro malware é inteiramente do Usuário, não podendo ser imputada qualquer obrigação ou responsabilidade à CellBroker neste sentido.

Isenção de responsabilidade:

À vista do exposto acima, o Usuário declara estar plenamente ciente de que a CellBroker não é e nem poderá ser responsabilizada por quaisquer problemas decorrentes da infraestrutura de responsabilidade do próprio Usuário, que inclui o hardware, os softwares, as licenças e o acesso à internet, bem como pelas decisões e/ou pelo funcionamento dos seus scripts.

O Usuário reconhece que a CellBroker não é responsável pela infraestrutura da Corretora (servidores, links, rede, segurança, etc.) e nem por problemas na BM&FBOVESPA S.A. - Bolsa de Valores, Mercadorias e Futuros ou em outras plataformas de negociação, bem como suas respectivas redes de comunicação, e que, portanto, será isenta da responsabilidade de indenizar qualquer dano ou prejuízo que o Usuário venha a ter ou sofrer em função da criação, utilização e execução dos scripts.

A CellBroker não tem qualquer relação ou ingerência sobre o armazenamento do código e dos scripts criados pelo Usuário, cuja guarda e manutenção é de exclusiva obrigação do próprio Usuário e, desta forma, não poderá a CellBroker ser responsabilizada em caso de perda ou mau uso de tais informações e dados.

Mesmo não sendo a Cellbroker obrigada ou responsável pela guarda/vigilância de tais informações, o Usuário autoriza expressamente a CellBroker, a qualquer momento e com a finalidade de auxílio na manutenção e suporte das informações, armazenar em suas trilhas de auditoria o código dos scripts criados pelo Usuário.

O Usuário concorda expressamente que, caso seja necessário, a CellBroker poderá analisar, depurar, corrigir ou desenvolver scripts à pedido do próprio Usuário, sendo certo que haverá um custo por hora/homem para alocação de mão de obra de programação.

Finalmente, o Usuário declara ter pleno conhecimento de que:

•O recurso para negociação só estará disponível em Corretoras que estejam homologadas com a solução de scripts do Tryd;

•A Corretora e a CellBroker não garantem a execução das ordens enviadas, devendo o Usuário calibrar o melhor preço para a execução das ordens;

•As ordens geradas pelos scripts seguem o mesmo fluxo das ordens normais, podendo ser rejeitadas pela corretora/bolsa em função dos limites de negociação e das regras que regulamentam o mercado de capitais (por exemplo, horários de negociação e estado do papel); e

•Toda comunicação através da rede mundial de computadores está sujeita a interrupções ou atrasos, podendo impedir ou prejudicar o envio de ordens ou a recepção de informações atualizadas podendo invalidar ordens ou negociações.

Processos são scripts escritos em Groovy que são executados pelo Tryd. Através dessa linguagem o usuário deverá implementar uma Classe que será responsável por executar os comandos disponibilizados pela API (Interface de Programação de Aplicativos) de Processos do Tryd.

Cada processo funciona de forma independente, sendo assim, a execução de um Processo não interfere na execução de outro. Isso é garantido pelo fato de que cada um é executado em sua prórpia linha de execução (Thread).

Após o Processo ser devidamente configurado e iniciado pelo usuário o mesmo será executado Tryd. O status de sua execução poderá ser monitorada através da tela de Processo de Script:

1.fundamentos_processos_01

Menu: Janela > Mostrar Visões > Outros > Script > Processos de Script

Da mesma forma que esse Processo pode ser iniciado a qualquer momento, ele também poderá ser interrompido pelo usuário, seja pela tela de Processos de Script diretamente, seja pelo próprio código do script.

A execução de um Processo somente irá acontecer quando:

▪A tela de Processos de Script estiver aberta e o usuário iniciar o Processo, utilizando o botão .

Podem ser interrompidos quando:

▪O usuário utilizar o botão pela tela de Processos de Script.

▪O Processo expirar.

▪A sua interrupção for programada pelo usuário.

▪ A tela de Processos de Script for fechada.

▪O Tryd for fechado.

A API de Processos do Tryd é composta de algumas classes que tem proporcionam ao usuário acesso a diversos recursos, tais como:

▪Indicadores de análise técnica.

▪Roteamento de ordens.

▪Exibição de mensagens.

▪Log de mensagens.

▪Armazenamento de valores.

▪Além dos recursos nativos da própria linguagem.

De todas as classes existentes na API (veja a documentação completa na seção Documentação da API) a mais importante é a classe Process.

Cada Processo criado pelo usuário deve ser uma subclasse desta classe abstrata.

Cada Processo em execução é uma instância da classe criada, que é filha de Process. Ao ser Parado, esta instância é descartada.

Para que o usuário possa interceptar os eventos e executar ações, basta que nessa subclasse os métodos corretos sejam sobrescritos.

Observe abaixo uma subclasse de Process:

import stScript.process.api.*;

public class UserProcess extends Process {

void onStart() {

// Chamado apenas uma vez, quando o processo

// for iniciado.

}

void onQuoteEvent(QuoteEvent event) {

// Chamado sempre que algum dos papeis

// monitorados pelo processo sofrer

// alterações.

}

void onOrderChangeEvent(OrderChangeEvent event) {

// Chamado sempre que ocorrer uma

// modificação nos dados de uma ordem

// enviada por este processo.

}

void onStop() {

// Chamado apenas uma vez, quando o processo

// parar.

}

Note que alguns eventos recebem parâmetros contendo dados relativos ao evento, como no caso do método onQuoteEvent(QuoteEvent event), que recebe um objeto do tipo QuoteEvent, contendo os dados do papel que sofreu alterações.

A criação de um Processo envolve algumas etapas:

1.Criar de uma classe filha de Process.

2.Implementar os métodos necessários para realizar a interceptação dos eventos.

3.Iniciar a execução do Processo

Para o primeiro passso, abra a tela de Processos de Script e, em seguida, clique no botão Adicionar na parte superior da tela.

Criando um Processo

Tela com o botão Adicionar destacado

Janela de cadastro do Processo

Tela de cadastro do Processo, com o modelo da classe a ser implementada

A janela de cadastro contém um molde da classe filha, mostrando os métodos relativos aos eventos que podem ser interceptados.

O exemplo a seguir mostra como enviar um e-mail no momento em que o Processo for iniciado. Para executar uma ação no momento em que o Processo for iniciado, adicione o código do envio de e-mail no método onStart, como é mostrado abaixo:

import stScript.process.api.*;

public class UserProcess extends Process {

void onStart() {

sendMail(

"destino@domain.com",

"Assunto do e-mail",

"Texto do e-mail"

);

}

Note que como a intenção é executar uma ação apenas no momento em que o Processo for iniciado, não é preciso manter os demais métodos na classe.

Com a classe criada, preencha o campo Nome, que será utilizado para identificar o processo na lista de processos. Após isso, clique no botão OK para confirmar a criação do novo Processo e voltar à tela de Processos de Script.

Janela com o processo criado

Tela de Processos de Script com o Processo "Envio de email"

Como último passo, clique com o botão direito no Processo que foi cadastrado e selecione a opção Iniciar, como mostrado na imagem acima.

O Processo será iniciado e enviará um e-mail, de acordo com o que foi programado na classe.

Como o código do envio do e-mail foi adicionado no método onStart, o envio será feito apenas uma vez, no momento em que o Processo for iniciado.

Na seção Exemplos podem ser encontrados outros tipos de Processos que envolvem interceptar eventos de cotação de papeis, utilização de Indicadores de Analise Técnica, entre outros.

Um Processo cadastrado pode estar:

•Rodando: Um Processo rodando é aquele que é capaz de responder aos eventos e realizar ações.

•Interrompido: Um Processo interrompido não é capaz de responder a nenhum evento.

Através do Estado do Processo é possível saber se ele está rodando ou está interrompido:

• Iniciado: O processo que estiver Iniciado será capaz de responder aos eventos. Isso significa que o processo será notificado quando um evento acontecer. Para que um processo se encontre nesse estado, é preciso clicar com o botão direito no processo na janela de Processos de Script e selecione a opção Iniciar, ou marcar vários processos de uma única vez e clicar no botão Iniciar processos marcados na topo da janela.

• Parando: Estado intermediário, indicando que o processo está sendo interrompido e entrará do estado de Parado.

• Parado: Todo processo encontra-se com no estado Parado após ser cadastrado. Neste estado, o processo está interrompido e não pode responder aos eventos, não executando nenhuma ação. Estes Processos poderão ser iniciados a qualquer momento. Para interromper um processo, vá até a visão de Processos de Script, clique com o botão direito no processo e selecione a opção Solicitar parada, ou marque vários processos de uma única vez e clique no botão Solicitar parada dos processos marcados no topo da janela. Com isso, o processo entrará no estado de Parando e quando for definitivamente interrompido estará com o estado de Parado.

• Expirando: Estado intermediário, indicando que o processo está sendo interrompido e entrará no estado de Expirado.

• Expirado: Um processo Expirado indica que a sua validade acabou. Esse processo está interrompido e não poderá ser modificado para o estado Iniciado diretamente, somente após a sua data de validade ter sido modificada para ser posterior à data atual, ou ter a sua validade removida.

• Finalizando: Estado intermediário, indicando que o processo está sendo interrompido e entrará no estado de Finalizado.

• Finalizado: O processo está Finalizado quando o usuário decide que o mesmo não deve ser executado novamente. Para indicar que o processo está Finalizado, utilize a função markProcessFinalization(), fazendo com que o processo entre no estado Finalizando. Esses processos se comportam como se estivessem Parados e podem ser iniciados a qualquer momento, respeitando a sua validade.

Estas transições de status poderão ser interceptadas pelo usuário em sua subclasse, bastando sobrescrever os seguintes métodos:

•onStart(): Quando um Processo é Iniciado, o método onStart() será chamado, permitindo que o usuário saiba quando o processo iniciou. Apenas a partir desse momento é o que os recursos do Processo poderão ser utilizados. Entende-se como recursos todos os métodos da classe Process. Este método será chamado apenas uma vez.

•onStop(): Ao ser interrompido, o método onStop() será chamado, independente se o processo foi interrompido pela solicitação na tela de Processos de Script (Parado), se expirou (Expirado) ou se finalizou (Finalizado).

Abaixo poderá ser visualizado como ocorrem as transições de status, quais métodos são chamados e quando os recursos de Process estarão disponíveis.

Diagrama

Diagrama do Ciclo de Vida de um Processo

Atenção

•Cada vez que um Processo entra em execução, uma nova instância da subclasse é criada, e quando é interrompido essa instância é descartada, não guardando valores para a próxima execução.

•Os Processos somente estarão rodando enquanto a tela de Processos de Script estiver aberta. Quando a tela for fechada, a parada dos Processos será solicitada, e a tela só poderá ser aberta novamente quando os Processos que estavam rodando forem completamente interrompidos.

•Ao fechar o sistema, os Processos serão interrompidos.

•No caso de Processos que enviam ordens, o logoff do roteamento causará uma solicitação de parada dos mesmos.

Todas as classes disponibilizadas para o desenvolvimento de Processos de Script estão documentadas utilizando o padrão Javadoc.

Em Documentação da API de Scripts do Tryd é possível acessar a documentação completa da API de Scripts do Tryd.

Foram desenvolvidos alguns exemplos de processos para mostrar o que pode ser feito com a API.

Atenção: Os exemplos descritos abaixo são meramente ilustrativos. A sua utilização é de inteira responsabilidade do usuário.

Alerta por valor:

Este processo irá exibir uma mensagem quando o valor do papel "PETR4" cruzar a casa dos R$ 22,00.

import stScript.process.api.*;

public class UserProcess extends Process {

void onStart() {

// Monitorando o papel

requestUpdates( "PETR4" );

}

void onQuoteEvent( QuoteEvent event ) {

def papel = event.getSecurity();

def last = papel.last();

// Faz o teste

if ( last > 22.00 ) {

// Mostra a mensagem

showPopupMessage(

"Valor de " + papel.code() + " ultrapassou R\$ 22,00."

);

// Interrompe o processo

markProcessFinalization();

}

Envio de ordens por Cruzamento de Médias Móveis

Neste exemplo, um processo que monitora os dados do papel "PETR4" analisa o seu histórico em busca de um cruzamento entre duas médias móveis

•A primeira média móvel simples é de 3 dias.

•A segunda média móvel simples é de 21 dias.

Quando o processo detecta esse cruzamento, ele o interpreta para saber se deve enviar uma ordem de compra ou de venda.

import stScript.process.api.*;

import stScript.db.api.*;

public class UserProcess extends Process {

// Indicador de "Compra" ou "Venda".

def side = "BUY";

// Indica se a estratégia está liberada para realizar o envio de ordens ou não.

// Sempre que uma ponta (compra, por exemplo) é enviada, essa flag é modificada

// para false. Ela somente será true quando a confirmação de execução em relação

// a essa ordem for recebida.

def sendNext = true;

// Número da última ordem enviada.

def lastSentOrderId = "";

void onStart() {

// Monitorando o papel.

requestUpdates( "PETR4" );

}

void onQuoteEvent( QuoteEvent event ) {

def security = event.getSecurity();

// Solicita os dados históricos do papel (1 minuto)

def historicalData = requestHistoricalData(

security.code(),

HistoricalData.HistoryInterval.MINUTE01

);

// Obtém o objeto que realiza os cálculos do indicador

def indicatorBuilder = getIndicatorBuilder();

def ma3days = indicatorBuilder.MA( historicalData.close(), 3, IndicatorBuilder.ExtendedMAType.SMA );

def ma21days = indicatorBuilder.MA( historicalData.close(), 21, IndicatorBuilder.ExtendedMAType.SMA );

if ( ma3days.size() > 1 && ma21days.size() > 1 ) {

def lastMa3daysValue = ma3days.value( ma3days.size() - 1 );

def lastMa21daysValue = ma21days.value( ma21days.size() - 1 );

def nextToLast3daysValue = ma3days.value( ma3days.size() - 2 );

def nextToLast21daysValue = ma21days.value( ma21days.size() - 2 );

def close = historicalData.close().value( historicalData.close().size() - 1 );

if ( "BUY".equals( side ) ) {

// Quando a de 3 cruzar a de 21 para cima, então, COMPRA

if ( ( lastMa3daysValue > lastMa21daysValue )

&& ( nextToLast3daysValue < nextToLast21daysValue ) ) {

def formatter = java.text.NumberFormat.getInstance();

def message = new StringBuilder()

.append( "Comprar " )

.append( security.code() )

.append( ".\n\n" )

.append( "MA de 3 cruzou MA de 21 para cima: " )

.append( formatter.format( lastMa3daysValue ) )

.append( " - " )

.append( formatter.format( lastMa21daysValue ) )

.toString();

// Envia um email em relação ao cruzamento

// Para enviar o e-mail, basta descomentar e

// configurar o seu email no lugar de:

// seu_email@domain.com

// sendMail(

//"seu_email@domain.com",

//"Cruzamento de Média Móvel" ,

//message

//);

// Loga uma mensagem de depuração em relação ao cruzamento

logMessage( "Cruzamento de Média Móvel \n" + message );

if ( ! sendNext ) {

logMessage( "Aguardando confirmação da ordem anterior" );

return;

}

// Envia a ordem

def response = sendBuyOrder( security.code(), 100, security.ask() );

if ( response.routed() ){

// Armazena o número da última ordem enviada

lastSentOrderId = response.getRoutedOrder().getOrderId();

// Indica que deve esperar pela confirmação de execução da ordem

sendNext = false;

// Loga uma mensagem de depuração em relação ao envio da ordem

logMessage( "Enviou ordem de compra número " + lastSentOrderId );

} else {

// Loga uma mensagem de depuração em relação ao erro no envio da ordem

logMessage( "Erro no envio da ordem de compra:\n" + response.getWsResponseXml() );

}

// Quando a de 21 cruzar a de 3 para cima, então, VENDE

} else if ( "SELL".equals( side ) ) {

if ( ( lastMa3daysValue < lastMa21daysValue )

&& ( nextToLast3daysValue > nextToLast21daysValue ) ) {

def formatter = java.text.NumberFormat.getInstance();

def message = new StringBuilder()

.append( "Vender " )

.append( security.code() )

.append( ".\n\n" )

.append( "MA de 21 cruzou MA de 3 para cima: " )

.append( formatter.format( lastMa21daysValue ) )

.append( " - " )

.append( formatter.format( lastMa3daysValue ) )

.toString();

// Envia um email em relação ao cruzamento

// Para enviar o e-mail, basta descomentar e

// configurar o seu email no lugar de:

// seu_email@domain.com

//sendMail(

//"seu_email@domain.com",

//"Cruzamento de Média Móvel" ,

//message

//);

// Loga uma mensagem de depuração em relação ao cruzamento

logMessage( "Cruzamento de Média Móvel \n" + message );

if ( ! sendNext ) {

logMessage( "Aguardando confirmação da ordem anterior" );

return;

}

// Envia a ordem

def response = sendSellOrder( security.code(), 100, security.bid() );

if ( response.routed() ){

// Armazena o número da última ordem enviada

lastSentOrderId = response.getRoutedOrder().getOrderId();

// Indica que deve esperar pela confirmação de execução da ordem

sendNext = false;

// Loga uma mensagem de depuração em relação ao envio da ordem

logMessage( "Enviou ordem de venda número " + lastSentOrderId );

} else {

// Loga uma mensagem de depuração em relação ao erro no envio da ordem

logMessage( "Erro no envio da ordem de venda:\n" + response.getWsResponseXml() );

}

void onOrderChangeEvent( OrderChangeEvent event ) {

def order = event.getChangedOrder();

logMessage( "Identificada modificação na ordem " + order.getOrderId() );

// Só interessam as atualizações referentes à última ordem

if ( ! lastSentOrderId.equals( order.getOrderId() ) ) {

return;

}

// Se a última ordem foi executada, então libera a estratégia para continuar

// (Somente considerando execução total)

if ( order.getStatus().equals( Order.Status.FILLED ) ) {

logMessage( "Execução identificada na ordem " + order.getOrderId() );

// Libera a estratégia

sendNext = true;

// Troca o lado da estratégia

side = ( "BUY".equals( side ) ? "SELL" : "BUY" );

// Limpa o controle sobre a ultima ordem

lastSentOrderId = "";

} else if ( order.getStatus().equals( Order.Status.CANCELED ) || order.getStatus().equals( Order.Status.REJECTED ) ) {

// Libera a estratégia para tentar realizar a mesma operação novamente

// pois, nesse caso, não será modificado o lado da estratégia

sendNext = true;

// Limpa o controle sobre a última ordem

lastSentOrderId = "";

}