Vytváranie obchodov

Trade opisuje jednu pozíciu: jej pár (základnú a kótovanú menu), smer, vstupnú a výstupnú cenu, veľkosť, čas otvorenia a zatvorenia a voliteľný poplatok. Najrýchlejšie ho vytvoríte cez Trade::make(), ktoré prijme obyčajné skaláry a číselné polia za vás obalí:

use Illuminate\Support\Carbon;
use RoundlyConsulting\TradingAnalytics\DataTransferObjects\Trade;
use RoundlyConsulting\TradingAnalytics\Enums\Direction;

$trade = Trade::make(
    baseCurrency: 'BTC',
    quoteCurrency: 'USD',
    openPrice: '45000.00',
    closePrice: '45500.00',
    size: '0.1',
    direction: Direction::BUY,                      // or the string 'buy' / 'sell'
    openTime: Carbon::create(2024, 1, 15, 12, 30),  // or a parseable date string
    commission: '15.00',                            // optional
    closeTime: Carbon::create(2024, 1, 15, 14, 30), // omit for an open position
);

Z poľa

Vytvorenie z poľa, napríklad z dát z API:

$trade = Trade::fromArray([
    'base_currency' => 'BTC',
    'quote_currency' => 'USD',
    'open_price' => '45000.00',
    'close_price' => '45500.00',
    'size' => '0.1',
    'direction' => 'buy',
    'open_time' => '2024-01-15 12:30:00',
    'commission' => '15.00',               // optional
    'close_time' => '2024-01-15 14:30:00', // optional
]);

Z ľubovoľného riadku

Trade::fromRow() prečíta riadok v akomkoľvek tvare, ktorý vaša aplikácia vytvorí — pole, riadok stdClass z query buildera, model Eloquent, ľubovoľný Arrayable alebo verejné vlastnosti obyčajného objektu — a Trade vráti tak, ako je. Trade::collect() lenivo premapuje celý iterovateľný zdroj takýchto riadkov; modely, casty a dopyty rozoberá sekcia Načítanie histórie obchodov:

use Illuminate\Support\Facades\DB;
use RoundlyConsulting\TradingAnalytics\DataTransferObjects\Trade;

$trade = Trade::fromRow(DB::table('trades')->find($id));   // stdClass row
$trade = Trade::fromRow(TradeRecord::findOrFail($id));      // your Eloquent model

// Any iterable of rows (or Trades, or a mix), mapped lazily
$trades = Trade::collect(DB::table('trades')->orderBy('close_time')->orderBy('id')->lazy());

Polia

Kľúč poľa	Pomenovaný argument	Typ	Povinné	Poznámka
`base_currency`	`baseCurrency`	string	✓	Neprázdna, napr. BTC.
`quote_currency`	`quoteCurrency`	string	✓	Neprázdna, napr. USD.
`open_price`	`openPrice`	string\|int\|float\|NumericValueAsString	✓	Vstupná cena; väčšia ako 0.
`close_price`	`closePrice`	string\|int\|float\|NumericValueAsString	✓	Výstupná cena; pri otvorenej pozícii cena, ktorou sa oceňuje. Nesmie byť záporná — 0 znamená úplnú stratu.
`size`	`size`	string\|int\|float\|NumericValueAsString	✓	Obchodované množstvo, väčšie ako 0; hodnota = size × vstupná cena.
`direction`	`direction`	Direction\|BackedEnum\|string	✓	buy alebo sell — prípadne ľubovoľný enum s týmito reťazcovými hodnotami, napr. vlastný cast modelu.
`open_time`	`openTime`	DateTimeInterface\|string	✓	Ľubovoľný DateTimeInterface (Carbon, cast datetime) alebo reťazec dátumu, ktorý sa dá parsovať.
`commission`	`commission`	string\|int\|float\|NumericValueAsString\|null	—	Poplatky; čisté hodnoty ich odpočítajú. Obchod bez poplatku sa počíta ako 0.
`close_time`	`closeTime`	DateTimeInterface\|string\|null	—	Vynechajte (null) pri otvorenej pozícii; nesmie byť pred časom otvorenia.

Otvorené pozície

Pri pozícii, ktorá je stále otvorená, čas zatvorenia vynechajte. Jej closePrice je cena, ktorou sa pozícia oceňuje: otvorené obchody vstupujú do nerealizovaného P&L, kým série, expectancy, pomer rizika a výnosu, miera výhier po obdobiach, drawdown a Sharpeho a Sortinov pomer počítajú len uzavreté obchody.

// No close time: the position is still open.
// closePrice is the price the position is valued at (unrealized P&L).
$open = Trade::make(
    baseCurrency: 'ETH',
    quoteCurrency: 'USD',
    openPrice: '3000',
    closePrice: '3120',
    size: '2',
    direction: 'buy',
    openTime: '2024-03-04 08:00',
);

$open->isOpen();                  // true
$open->isRealized();              // false
(string) $open->profitAndLoss();  // '240.0000000000'

Validácia

Pri vytváraní sa vyhodí InvalidTradeException, ak je mena prázdna, čas zatvorenia predchádza času otvorenia, veľkosť alebo vstupná cena je 0 či menej, výstupná cena je záporná, povinné pole chýba alebo je null, pole má nesprávny typ alebo smer nie je buy ani sell. Výstupná cena 0 — úplná strata — je platná:

use RoundlyConsulting\TradingAnalytics\Exceptions\InvalidTradeException;

try {
    Trade::fromArray(['base_currency' => 'BTC', 'quote_currency' => 'USD']);
} catch (InvalidTradeException $e) {
    $e->getMessage(); // "A trade is missing the required 'open_price' field."
}

Trade::make('BTC', 'USD', '1', '1', '1', 'hold', '2024-01-01');
// InvalidTradeException: 'hold' is not a valid trade direction; expected one of: buy, sell.

Trade::make('BTC', 'USD', '45000', '45500', '0', 'buy', '2024-01-01');
// InvalidTradeException: A trade's size must be greater than 0; got '0.0000000000'.

Trade::fromArray([...$row, 'open_time' => 1709283600]);
// InvalidTradeException: A trade's 'open_time' field must be a date string or DateTimeInterface; got int.

Plná kontrola

Ak potrebujete plnú kontrolu, vytvorte Trade priamo s poliami NumericValueAsString:

use RoundlyConsulting\TradingAnalytics\DataTransferObjects\NumericValueAsString;

$trade = new Trade(
    baseCurrency: 'BTC',
    quoteCurrency: 'USD',
    openPrice: new NumericValueAsString('45000.00'),
    closePrice: new NumericValueAsString('45500.00'),
    size: new NumericValueAsString('0.1'),
    direction: Direction::BUY,
    openTime: Carbon::create(2024, 1, 15, 12, 30),
);

Čísla samotného obchodu sa uchovávajú presne. Trade::make(), fromArray() a fromRow() zachovajú každú sumu na jej vlastný počet desatinných miest — aspoň 10, vrátane exponenciálneho zápisu (1.5e-14 ich zachová 15) — a odovzdaný NumericValueAsString si ponechá svoju škálu (aspoň 10); priamo vytvorený Trade si ponechá škálu svojich polí. Veľkosť so 14 desatinnými miestami ani drobná pozícia sa teda nikdy neorežú na 10 desatinných miest a to, čo ukážu agregáty, obmedzuje len škála behu — zvýšte ju zodpovedajúco:

use RoundlyConsulting\TradingAnalytics\Facades\TradingAnalytics;

$trade = Trade::make(
    baseCurrency: 'TKN',
    quoteCurrency: 'USD',
    openPrice: '0.000000000001234',
    closePrice: '0.000000000002000',
    size: '1000000',
    direction: 'buy',
    openTime: '2024-01-01 00:00',
);

$trade->openPrice->toRawString();       // '0.000000000001234' — all 15 decimals kept
$trade->profitAndLoss()->toRawString(); // '0.000000766000000'

// Raise the run's scale to match: aggregates use the run's scale (default 10)
TradingAnalytics::for([$trade])->scale(18)->calculate();

Prejavte lásku k open source

Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.

Ďalšie spôsoby podpory vrátane kryptomien

Odoslaním daru súhlasíte s našimi podmienkami prijímania darov.

Podporte našu open-source prácu Pridajte sa k nám na Patreone

Chcete to zabudovať do svojho produktu?

Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.

Ponuka do 48 hodín Prezrieť všetky balíky