feat: 初始化 cryptoHermes 行情网关 v1 MVP + harness 工程文档

Binance USDⓈ-M Futures 行情网关，给上游 Hermes 量化分析引擎提供单一聚合
接口 /v1/market/context（K 线 + funding + OI + 多空比 + taker volume）。
只读公共行情，不下单、不接私钥、不查账户。

## v1 实现范围（Milestone 1-5）

- Clean Architecture 4 层（controller/usecase/repo/entity），接口边界在
  internal/usecase/ports.go
- Binance Futures REST client（K 线 / ticker24h / funding / OI / 多空比
  / taker volume 共 9 个接口），全链路 string 价格避免 float64 精度问题
- TimescaleDB 5 张 hypertable（market_klines / funding_rates /
  open_interest / long_short_ratio / taker_buy_sell_volume），主键含
  时间维度，UpsertMany 幂等
- robfig/cron 定时采集（15m/1h/4h/1d/1w 多周期 K 线 + 衍生品 15 分钟
  落库），未收线 K 线 (close_time > now) 由 mapper/repo 双重过滤
- pkg/httpclient 统一限流（默认 20 req/s, burst 40）+ 重试，避免触发
  Binance 2400 weight/min IP 上限
- /v1/market/context 聚合接口：errgroup 并发拉 snapshot/funding/OI，DB
  K 线不足 200 根回源 Binance 异步补
- cmd/backfill CLI 支持指定 from/to 大段回填（Binance 历史 OI / 多空比
  官方只保留 30 天，必须自己存）
- Docker Compose + Makefile + golang-migrate，本地一键启

技术指标（support/resistance/Vegas/箱体）留待 v2，技术段返回空对象 +
warning 占位。

## Harness 工程文档

- AGENTS.md — AI agent 工作速查（10 个章节）
- ai/project-map.md — 仓库结构、扩展点、控制流
- ai/risk-guardrails.md — G1-G10 守卫规则（每条带可机械验证命令）
- ai/adr/0001-architecture-foundations.md — 9 条架构基础决策
- ai/task-templates.md — 6 种任务契约模板
- ai/harness-health.md — 当前 harness 健康度评估

3 个 grep 守卫已验证通过：controller / usecase 无具体实现依赖，全项目
无私钥/签名字段。

internal/repo/persistent/postgres/funding_repo.go

@@ -0,0 +1,86 @@
+package postgres
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"cryptoHermes/internal/entity"
+)
+
+type FundingRepo struct {
+	pool *pgxpool.Pool
+}
+
+func NewFundingRepo(pool *pgxpool.Pool) *FundingRepo {
+	return &FundingRepo{pool: pool}
+}
+
+const fundingUpsertSQL = `
+INSERT INTO funding_rates (source, symbol, funding_time, funding_rate, mark_price)
+VALUES ($1, $2, $3, $4, NULLIF($5, '')::NUMERIC)
+ON CONFLICT (source, symbol, funding_time) DO UPDATE SET
+  funding_rate = EXCLUDED.funding_rate,
+  mark_price = EXCLUDED.mark_price
+`
+
+func (r *FundingRepo) UpsertMany(ctx context.Context, items []entity.FundingRate) error {
+	if len(items) == 0 {
+		return nil
+	}
+	tx, err := r.pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+
+	for _, f := range items {
+		if f.FundingRate == "" || f.FundingTime == 0 {
+			continue
+		}
+		if _, err := tx.Exec(ctx, fundingUpsertSQL,
+			f.Source, f.Symbol, f.FundingTime, f.FundingRate, f.MarkPrice,
+		); err != nil {
+			return fmt.Errorf("upsert funding %s@%d: %w", f.Symbol, f.FundingTime, err)
+		}
+	}
+	return tx.Commit(ctx)
+}
+
+const fundingFindSQL = `
+SELECT source, symbol, funding_time, funding_rate::text, COALESCE(mark_price::text, '')
+FROM funding_rates
+WHERE symbol = $1
+ORDER BY funding_time DESC
+LIMIT $2
+`
+
+func (r *FundingRepo) FindRecent(ctx context.Context, symbol string, limit int) ([]entity.FundingRate, error) {
+	if limit <= 0 {
+		limit = 100
+	}
+	rows, err := r.pool.Query(ctx, fundingFindSQL, symbol, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	out := make([]entity.FundingRate, 0, limit)
+	for rows.Next() {
+		var f entity.FundingRate
+		var mark sql.NullString
+		if err := rows.Scan(&f.Source, &f.Symbol, &f.FundingTime, &f.FundingRate, &mark); err != nil {
+			return nil, err
+		}
+		if mark.Valid {
+			f.MarkPrice = mark.String
+		}
+		out = append(out, f)
+	}
+	for i, j := 0, len(out)-1; i < j; i, j = i+1, j-1 {
+		out[i], out[j] = out[j], out[i]
+	}
+	return out, rows.Err()
+}

internal/repo/persistent/postgres/kline_repo.go

@@ -0,0 +1,114 @@
+package postgres
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"cryptoHermes/internal/entity"
+)
+
+type KlineRepo struct {
+	pool *pgxpool.Pool
+}
+
+func NewKlineRepo(pool *pgxpool.Pool) *KlineRepo {
+	return &KlineRepo{pool: pool}
+}
+
+const klineUpsertSQL = `
+INSERT INTO market_klines (
+  source, symbol, interval, open_time, close_time,
+  open, high, low, close,
+  volume, quote_volume,
+  trade_count, taker_buy_base_volume, taker_buy_quote_volume,
+  updated_at
+) VALUES (
+  $1, $2, $3, $4, $5,
+  $6, $7, $8, $9,
+  $10, $11,
+  $12, $13, $14,
+  now()
+)
+ON CONFLICT (source, symbol, interval, open_time) DO UPDATE SET
+  close_time = EXCLUDED.close_time,
+  open = EXCLUDED.open,
+  high = EXCLUDED.high,
+  low = EXCLUDED.low,
+  close = EXCLUDED.close,
+  volume = EXCLUDED.volume,
+  quote_volume = EXCLUDED.quote_volume,
+  trade_count = EXCLUDED.trade_count,
+  taker_buy_base_volume = EXCLUDED.taker_buy_base_volume,
+  taker_buy_quote_volume = EXCLUDED.taker_buy_quote_volume,
+  updated_at = now()
+`
+
+func (r *KlineRepo) UpsertMany(ctx context.Context, items []entity.Kline) error {
+	if len(items) == 0 {
+		return nil
+	}
+	tx, err := r.pool.Begin(ctx)
+	if err != nil {
+		return fmt.Errorf("begin: %w", err)
+	}
+	defer tx.Rollback(ctx)
+
+	for _, k := range items {
+		if !k.IsClosed {
+			continue
+		}
+		_, err := tx.Exec(ctx, klineUpsertSQL,
+			k.Source, k.Symbol, k.Interval, k.OpenTime, k.CloseTime,
+			k.Open, k.High, k.Low, k.Close,
+			k.Volume, k.QuoteVolume,
+			k.TradeCount, k.TakerBuyBaseVolume, k.TakerBuyQuoteVolume,
+		)
+		if err != nil {
+			return fmt.Errorf("upsert kline %s/%s@%d: %w", k.Symbol, k.Interval, k.OpenTime, err)
+		}
+	}
+	return tx.Commit(ctx)
+}
+
+const klineFindSQL = `
+SELECT source, symbol, interval, open_time, close_time,
+  open::text, high::text, low::text, close::text,
+  volume::text, quote_volume::text,
+  trade_count, taker_buy_base_volume::text, taker_buy_quote_volume::text
+FROM market_klines
+WHERE symbol = $1 AND interval = $2
+ORDER BY open_time DESC
+LIMIT $3
+`
+
+func (r *KlineRepo) FindRecent(ctx context.Context, symbol, interval string, limit int) ([]entity.Kline, error) {
+	if limit <= 0 {
+		limit = 300
+	}
+	rows, err := r.pool.Query(ctx, klineFindSQL, symbol, interval, limit)
+	if err != nil {
+		return nil, fmt.Errorf("query: %w", err)
+	}
+	defer rows.Close()
+
+	out := make([]entity.Kline, 0, limit)
+	for rows.Next() {
+		var k entity.Kline
+		if err := rows.Scan(
+			&k.Source, &k.Symbol, &k.Interval, &k.OpenTime, &k.CloseTime,
+			&k.Open, &k.High, &k.Low, &k.Close,
+			&k.Volume, &k.QuoteVolume,
+			&k.TradeCount, &k.TakerBuyBaseVolume, &k.TakerBuyQuoteVolume,
+		); err != nil {
+			return nil, fmt.Errorf("scan: %w", err)
+		}
+		k.IsClosed = true
+		out = append(out, k)
+	}
+	for i, j := 0, len(out)-1; i < j; i, j = i+1, j-1 {
+		out[i], out[j] = out[j], out[i]
+	}
+	return out, rows.Err()
+}

internal/repo/persistent/postgres/long_short_ratio_repo.go

@@ -0,0 +1,94 @@
+package postgres
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"cryptoHermes/internal/entity"
+)
+
+type LongShortRatioRepo struct {
+	pool *pgxpool.Pool
+}
+
+func NewLongShortRatioRepo(pool *pgxpool.Pool) *LongShortRatioRepo {
+	return &LongShortRatioRepo{pool: pool}
+}
+
+const lsUpsertSQL = `
+INSERT INTO long_short_ratio (
+  source, symbol, period, ratio_type, timestamp,
+  long_short_ratio, long_value, short_value
+) VALUES (
+  $1, $2, $3, $4, $5,
+  $6,
+  NULLIF($7, '')::NUMERIC,
+  NULLIF($8, '')::NUMERIC
+)
+ON CONFLICT (source, symbol, period, ratio_type, timestamp) DO UPDATE SET
+  long_short_ratio = EXCLUDED.long_short_ratio,
+  long_value = EXCLUDED.long_value,
+  short_value = EXCLUDED.short_value
+`
+
+func (r *LongShortRatioRepo) UpsertMany(ctx context.Context, items []entity.LongShortRatio) error {
+	if len(items) == 0 {
+		return nil
+	}
+	tx, err := r.pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+
+	for _, ls := range items {
+		if ls.LongShortRatio == "" || ls.Timestamp == 0 {
+			continue
+		}
+		if _, err := tx.Exec(ctx, lsUpsertSQL,
+			ls.Source, ls.Symbol, ls.Period, ls.RatioType, ls.Timestamp,
+			ls.LongShortRatio, ls.LongValue, ls.ShortValue,
+		); err != nil {
+			return fmt.Errorf("upsert ls %s/%s/%s@%d: %w", ls.Symbol, ls.Period, ls.RatioType, ls.Timestamp, err)
+		}
+	}
+	return tx.Commit(ctx)
+}
+
+const lsFindSQL = `
+SELECT source, symbol, period, ratio_type, timestamp,
+       long_short_ratio::text,
+       COALESCE(long_value::text, ''),
+       COALESCE(short_value::text, '')
+FROM long_short_ratio
+WHERE symbol = $1 AND period = $2 AND ratio_type = $3
+ORDER BY timestamp DESC
+LIMIT $4
+`
+
+func (r *LongShortRatioRepo) FindRecent(ctx context.Context, symbol, period, ratioType string, limit int) ([]entity.LongShortRatio, error) {
+	if limit <= 0 {
+		limit = 100
+	}
+	rows, err := r.pool.Query(ctx, lsFindSQL, symbol, period, ratioType, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	out := make([]entity.LongShortRatio, 0, limit)
+	for rows.Next() {
+		var ls entity.LongShortRatio
+		if err := rows.Scan(&ls.Source, &ls.Symbol, &ls.Period, &ls.RatioType, &ls.Timestamp,
+			&ls.LongShortRatio, &ls.LongValue, &ls.ShortValue); err != nil {
+			return nil, err
+		}
+		out = append(out, ls)
+	}
+	for i, j := 0, len(out)-1; i < j; i, j = i+1, j-1 {
+		out[i], out[j] = out[j], out[i]
+	}
+	return out, rows.Err()
+}

internal/repo/persistent/postgres/open_interest_repo.go

@@ -0,0 +1,82 @@
+package postgres
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"cryptoHermes/internal/entity"
+)
+
+type OpenInterestRepo struct {
+	pool *pgxpool.Pool
+}
+
+func NewOpenInterestRepo(pool *pgxpool.Pool) *OpenInterestRepo {
+	return &OpenInterestRepo{pool: pool}
+}
+
+const oiUpsertSQL = `
+INSERT INTO open_interest (source, symbol, period, timestamp, open_interest, open_interest_value)
+VALUES ($1, $2, $3, $4, $5, NULLIF($6, '')::NUMERIC)
+ON CONFLICT (source, symbol, period, timestamp) DO UPDATE SET
+  open_interest = EXCLUDED.open_interest,
+  open_interest_value = EXCLUDED.open_interest_value
+`
+
+func (r *OpenInterestRepo) UpsertMany(ctx context.Context, items []entity.OpenInterest) error {
+	if len(items) == 0 {
+		return nil
+	}
+	tx, err := r.pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+
+	for _, o := range items {
+		if o.OpenInterest == "" || o.Timestamp == 0 {
+			continue
+		}
+		if _, err := tx.Exec(ctx, oiUpsertSQL,
+			o.Source, o.Symbol, o.Period, o.Timestamp, o.OpenInterest, o.OpenInterestValue,
+		); err != nil {
+			return fmt.Errorf("upsert oi %s/%s@%d: %w", o.Symbol, o.Period, o.Timestamp, err)
+		}
+	}
+	return tx.Commit(ctx)
+}
+
+const oiFindSQL = `
+SELECT source, symbol, period, timestamp,
+       open_interest::text, COALESCE(open_interest_value::text, '')
+FROM open_interest
+WHERE symbol = $1 AND period = $2
+ORDER BY timestamp DESC
+LIMIT $3
+`
+
+func (r *OpenInterestRepo) FindRecent(ctx context.Context, symbol, period string, limit int) ([]entity.OpenInterest, error) {
+	if limit <= 0 {
+		limit = 100
+	}
+	rows, err := r.pool.Query(ctx, oiFindSQL, symbol, period, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	out := make([]entity.OpenInterest, 0, limit)
+	for rows.Next() {
+		var o entity.OpenInterest
+		if err := rows.Scan(&o.Source, &o.Symbol, &o.Period, &o.Timestamp, &o.OpenInterest, &o.OpenInterestValue); err != nil {
+			return nil, err
+		}
+		out = append(out, o)
+	}
+	for i, j := 0, len(out)-1; i < j; i, j = i+1, j-1 {
+		out[i], out[j] = out[j], out[i]
+	}
+	return out, rows.Err()
+}

internal/repo/persistent/postgres/taker_volume_repo.go

@@ -0,0 +1,90 @@
+package postgres
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"cryptoHermes/internal/entity"
+)
+
+type TakerVolumeRepo struct {
+	pool *pgxpool.Pool
+}
+
+func NewTakerVolumeRepo(pool *pgxpool.Pool) *TakerVolumeRepo {
+	return &TakerVolumeRepo{pool: pool}
+}
+
+const takerUpsertSQL = `
+INSERT INTO taker_buy_sell_volume (source, symbol, period, timestamp, buy_sell_ratio, buy_volume, sell_volume)
+VALUES ($1, $2, $3, $4,
+  NULLIF($5, '')::NUMERIC,
+  NULLIF($6, '')::NUMERIC,
+  NULLIF($7, '')::NUMERIC)
+ON CONFLICT (source, symbol, period, timestamp) DO UPDATE SET
+  buy_sell_ratio = EXCLUDED.buy_sell_ratio,
+  buy_volume = EXCLUDED.buy_volume,
+  sell_volume = EXCLUDED.sell_volume
+`
+
+func (r *TakerVolumeRepo) UpsertMany(ctx context.Context, items []entity.TakerBuySellVolume) error {
+	if len(items) == 0 {
+		return nil
+	}
+	tx, err := r.pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+
+	for _, t := range items {
+		if t.Timestamp == 0 {
+			continue
+		}
+		if _, err := tx.Exec(ctx, takerUpsertSQL,
+			t.Source, t.Symbol, t.Period, t.Timestamp,
+			t.BuySellRatio, t.BuyVolume, t.SellVolume,
+		); err != nil {
+			return fmt.Errorf("upsert taker %s/%s@%d: %w", t.Symbol, t.Period, t.Timestamp, err)
+		}
+	}
+	return tx.Commit(ctx)
+}
+
+const takerFindSQL = `
+SELECT source, symbol, period, timestamp,
+       COALESCE(buy_sell_ratio::text, ''),
+       COALESCE(buy_volume::text, ''),
+       COALESCE(sell_volume::text, '')
+FROM taker_buy_sell_volume
+WHERE symbol = $1 AND period = $2
+ORDER BY timestamp DESC
+LIMIT $3
+`
+
+func (r *TakerVolumeRepo) FindRecent(ctx context.Context, symbol, period string, limit int) ([]entity.TakerBuySellVolume, error) {
+	if limit <= 0 {
+		limit = 100
+	}
+	rows, err := r.pool.Query(ctx, takerFindSQL, symbol, period, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	out := make([]entity.TakerBuySellVolume, 0, limit)
+	for rows.Next() {
+		var t entity.TakerBuySellVolume
+		if err := rows.Scan(&t.Source, &t.Symbol, &t.Period, &t.Timestamp,
+			&t.BuySellRatio, &t.BuyVolume, &t.SellVolume); err != nil {
+			return nil, err
+		}
+		out = append(out, t)
+	}
+	for i, j := 0, len(out)-1; i < j; i, j = i+1, j-1 {
+		out[i], out[j] = out[j], out[i]
+	}
+	return out, rows.Err()
+}

internal/repo/webapi/binance/client.go

@@ -0,0 +1,72 @@
+package binance
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+	"time"
+
+	"cryptoHermes/pkg/httpclient"
+)
+
+const sourceName = "binance"
+
+type Client struct {
+	http   *httpclient.Client
+	source string
+}
+
+type ClientOptions struct {
+	BaseURL    string
+	Timeout    time.Duration
+	RetryCount int
+	RPS        float64
+	Burst      int
+}
+
+func NewClient(opts ClientOptions) *Client {
+	return &Client{
+		http: httpclient.New(httpclient.Options{
+			BaseURL:    opts.BaseURL,
+			Timeout:    opts.Timeout,
+			RetryCount: opts.RetryCount,
+			RPS:        opts.RPS,
+			Burst:      opts.Burst,
+		}),
+		source: sourceName,
+	}
+}
+
+type ExternalAPIError struct {
+	Source     string
+	Path       string
+	StatusCode int
+	Message    string
+}
+
+func (e *ExternalAPIError) Error() string {
+	return fmt.Sprintf("%s %s status=%d: %s", e.Source, e.Path, e.StatusCode, e.Message)
+}
+
+func (c *Client) get(ctx context.Context, path string, q url.Values, out any) error {
+	status, body, _, err := c.http.Do(ctx, httpclient.Request{
+		Method: http.MethodGet,
+		Path:   path,
+		Query:  q,
+	})
+	if err != nil {
+		return &ExternalAPIError{Source: c.source, Path: path, StatusCode: 0, Message: err.Error()}
+	}
+	if status >= 400 {
+		return &ExternalAPIError{Source: c.source, Path: path, StatusCode: status, Message: string(body)}
+	}
+	if out == nil {
+		return nil
+	}
+	if err := json.Unmarshal(body, out); err != nil {
+		return &ExternalAPIError{Source: c.source, Path: path, StatusCode: status, Message: "decode: " + err.Error()}
+	}
+	return nil
+}

internal/repo/webapi/binance/derivatives.go

@@ -0,0 +1,116 @@
+package binance
+
+import (
+	"context"
+	"net/url"
+	"strconv"
+
+	"cryptoHermes/internal/entity"
+)
+
+func (c *Client) GetCurrentFunding(ctx context.Context, symbol string) (*entity.FundingRate, error) {
+	q := url.Values{}
+	q.Set("symbol", symbol)
+	var dto premiumIndexDTO
+	if err := c.get(ctx, "/fapi/v1/premiumIndex", q, &dto); err != nil {
+		return nil, err
+	}
+	return mapPremiumIndex(&dto), nil
+}
+
+func (c *Client) GetFundingHistory(ctx context.Context, symbol string, limit int) ([]entity.FundingRate, error) {
+	if limit <= 0 {
+		limit = 100
+	}
+	if limit > 1000 {
+		limit = 1000
+	}
+	q := url.Values{}
+	q.Set("symbol", symbol)
+	q.Set("limit", strconv.Itoa(limit))
+	var dto []fundingRateDTO
+	if err := c.get(ctx, "/fapi/v1/fundingRate", q, &dto); err != nil {
+		return nil, err
+	}
+	return mapFundingHistory(dto), nil
+}
+
+func (c *Client) GetCurrentOpenInterest(ctx context.Context, symbol string) (*entity.OpenInterest, error) {
+	q := url.Values{}
+	q.Set("symbol", symbol)
+	var dto openInterestDTO
+	if err := c.get(ctx, "/fapi/v1/openInterest", q, &dto); err != nil {
+		return nil, err
+	}
+	return mapOpenInterest(&dto, "current"), nil
+}
+
+func (c *Client) GetOpenInterestHistory(ctx context.Context, symbol, period string, limit int) ([]entity.OpenInterest, error) {
+	if limit <= 0 {
+		limit = 30
+	}
+	if limit > 500 {
+		limit = 500
+	}
+	q := url.Values{}
+	q.Set("symbol", symbol)
+	q.Set("period", period)
+	q.Set("limit", strconv.Itoa(limit))
+	var dto []openInterestHistDTO
+	if err := c.get(ctx, "/futures/data/openInterestHist", q, &dto); err != nil {
+		return nil, err
+	}
+	return mapOpenInterestHistory(dto, period), nil
+}
+
+func (c *Client) GetGlobalLongShortRatio(ctx context.Context, symbol, period string, limit int) ([]entity.LongShortRatio, error) {
+	dto, err := c.fetchLongShort(ctx, "/futures/data/globalLongShortAccountRatio", symbol, period, limit)
+	if err != nil {
+		return nil, err
+	}
+	return mapLongShort(dto, period, entity.RatioTypeGlobalAccount), nil
+}
+
+func (c *Client) GetTopTraderPositionRatio(ctx context.Context, symbol, period string, limit int) ([]entity.LongShortRatio, error) {
+	dto, err := c.fetchLongShort(ctx, "/futures/data/topLongShortPositionRatio", symbol, period, limit)
+	if err != nil {
+		return nil, err
+	}
+	return mapLongShort(dto, period, entity.RatioTypeTopTraderPosition), nil
+}
+
+func (c *Client) fetchLongShort(ctx context.Context, path, symbol, period string, limit int) ([]longShortRatioDTO, error) {
+	if limit <= 0 {
+		limit = 30
+	}
+	if limit > 500 {
+		limit = 500
+	}
+	q := url.Values{}
+	q.Set("symbol", symbol)
+	q.Set("period", period)
+	q.Set("limit", strconv.Itoa(limit))
+	var dto []longShortRatioDTO
+	if err := c.get(ctx, path, q, &dto); err != nil {
+		return nil, err
+	}
+	return dto, nil
+}
+
+func (c *Client) GetTakerBuySellVolume(ctx context.Context, symbol, period string, limit int) ([]entity.TakerBuySellVolume, error) {
+	if limit <= 0 {
+		limit = 30
+	}
+	if limit > 500 {
+		limit = 500
+	}
+	q := url.Values{}
+	q.Set("symbol", symbol)
+	q.Set("period", period)
+	q.Set("limit", strconv.Itoa(limit))
+	var dto []takerVolumeDTO
+	if err := c.get(ctx, "/futures/data/takerlongshortRatio", q, &dto); err != nil {
+		return nil, err
+	}
+	return mapTakerVolume(dto, symbol, period), nil
+}

internal/repo/webapi/binance/dto.go

@@ -0,0 +1,60 @@
+package binance
+
+type tickerDTO struct {
+	Symbol             string `json:"symbol"`
+	LastPrice          string `json:"lastPrice"`
+	PriceChange        string `json:"priceChange"`
+	PriceChangePercent string `json:"priceChangePercent"`
+	HighPrice          string `json:"highPrice"`
+	LowPrice           string `json:"lowPrice"`
+	Volume             string `json:"volume"`
+	QuoteVolume        string `json:"quoteVolume"`
+	OpenTime           int64  `json:"openTime"`
+	CloseTime          int64  `json:"closeTime"`
+}
+
+type premiumIndexDTO struct {
+	Symbol               string `json:"symbol"`
+	MarkPrice            string `json:"markPrice"`
+	IndexPrice           string `json:"indexPrice"`
+	LastFundingRate      string `json:"lastFundingRate"`
+	NextFundingTime      int64  `json:"nextFundingTime"`
+	Time                 int64  `json:"time"`
+}
+
+type fundingRateDTO struct {
+	Symbol      string `json:"symbol"`
+	FundingTime int64  `json:"fundingTime"`
+	FundingRate string `json:"fundingRate"`
+	MarkPrice   string `json:"markPrice"`
+}
+
+type openInterestDTO struct {
+	OpenInterest string `json:"openInterest"`
+	Symbol       string `json:"symbol"`
+	Time         int64  `json:"time"`
+}
+
+type openInterestHistDTO struct {
+	Symbol               string `json:"symbol"`
+	SumOpenInterest      string `json:"sumOpenInterest"`
+	SumOpenInterestValue string `json:"sumOpenInterestValue"`
+	Timestamp            int64  `json:"timestamp"`
+}
+
+type longShortRatioDTO struct {
+	Symbol         string `json:"symbol"`
+	LongShortRatio string `json:"longShortRatio"`
+	LongAccount    string `json:"longAccount"`
+	ShortAccount   string `json:"shortAccount"`
+	LongPosition   string `json:"longPosition"`
+	ShortPosition  string `json:"shortPosition"`
+	Timestamp      int64  `json:"timestamp"`
+}
+
+type takerVolumeDTO struct {
+	BuySellRatio string `json:"buySellRatio"`
+	BuyVol       string `json:"buyVol"`
+	SellVol      string `json:"sellVol"`
+	Timestamp    int64  `json:"timestamp"`
+}

internal/repo/webapi/binance/mapper.go

@@ -0,0 +1,170 @@
+package binance
+
+import (
+	"fmt"
+	"time"
+
+	"cryptoHermes/internal/entity"
+)
+
+func parseKlineRow(symbol, interval string, row []any) (entity.Kline, error) {
+	if len(row) < 12 {
+		return entity.Kline{}, fmt.Errorf("binance kline row has %d fields, expected >=12", len(row))
+	}
+	openTime, err := toInt64(row[0])
+	if err != nil {
+		return entity.Kline{}, fmt.Errorf("openTime: %w", err)
+	}
+	closeTime, err := toInt64(row[6])
+	if err != nil {
+		return entity.Kline{}, fmt.Errorf("closeTime: %w", err)
+	}
+	tradeCount, err := toInt64(row[8])
+	if err != nil {
+		return entity.Kline{}, fmt.Errorf("tradeCount: %w", err)
+	}
+
+	open, _ := row[1].(string)
+	high, _ := row[2].(string)
+	low, _ := row[3].(string)
+	closeP, _ := row[4].(string)
+	volume, _ := row[5].(string)
+	quoteVol, _ := row[7].(string)
+	takerBase, _ := row[9].(string)
+	takerQuote, _ := row[10].(string)
+
+	nowMs := time.Now().UnixMilli()
+	return entity.Kline{
+		Source:              sourceName,
+		Symbol:              symbol,
+		Interval:            interval,
+		OpenTime:            openTime,
+		CloseTime:           closeTime,
+		Open:                open,
+		High:                high,
+		Low:                 low,
+		Close:               closeP,
+		Volume:              volume,
+		QuoteVolume:         quoteVol,
+		TradeCount:          tradeCount,
+		TakerBuyBaseVolume:  takerBase,
+		TakerBuyQuoteVolume: takerQuote,
+		IsClosed:            closeTime < nowMs,
+	}, nil
+}
+
+func toInt64(v any) (int64, error) {
+	switch x := v.(type) {
+	case float64:
+		return int64(x), nil
+	case int64:
+		return x, nil
+	case int:
+		return int64(x), nil
+	default:
+		return 0, fmt.Errorf("unexpected type %T", v)
+	}
+}
+
+func mapTicker(d *tickerDTO) *entity.Ticker24h {
+	return &entity.Ticker24h{
+		Symbol:             d.Symbol,
+		LastPrice:          d.LastPrice,
+		PriceChange:        d.PriceChange,
+		PriceChangePercent: d.PriceChangePercent,
+		HighPrice:          d.HighPrice,
+		LowPrice:           d.LowPrice,
+		Volume:             d.Volume,
+		QuoteVolume:        d.QuoteVolume,
+		OpenTime:           d.OpenTime,
+		CloseTime:          d.CloseTime,
+	}
+}
+
+func mapPremiumIndex(d *premiumIndexDTO) *entity.FundingRate {
+	return &entity.FundingRate{
+		Source:      sourceName,
+		Symbol:      d.Symbol,
+		FundingTime: d.NextFundingTime,
+		FundingRate: d.LastFundingRate,
+		MarkPrice:   d.MarkPrice,
+	}
+}
+
+func mapFundingHistory(d []fundingRateDTO) []entity.FundingRate {
+	out := make([]entity.FundingRate, 0, len(d))
+	for _, x := range d {
+		out = append(out, entity.FundingRate{
+			Source:      sourceName,
+			Symbol:      x.Symbol,
+			FundingTime: x.FundingTime,
+			FundingRate: x.FundingRate,
+			MarkPrice:   x.MarkPrice,
+		})
+	}
+	return out
+}
+
+func mapOpenInterest(d *openInterestDTO, period string) *entity.OpenInterest {
+	return &entity.OpenInterest{
+		Source:       sourceName,
+		Symbol:       d.Symbol,
+		Period:       period,
+		Timestamp:    d.Time,
+		OpenInterest: d.OpenInterest,
+	}
+}
+
+func mapOpenInterestHistory(d []openInterestHistDTO, period string) []entity.OpenInterest {
+	out := make([]entity.OpenInterest, 0, len(d))
+	for _, x := range d {
+		out = append(out, entity.OpenInterest{
+			Source:            sourceName,
+			Symbol:            x.Symbol,
+			Period:            period,
+			Timestamp:         x.Timestamp,
+			OpenInterest:      x.SumOpenInterest,
+			OpenInterestValue: x.SumOpenInterestValue,
+		})
+	}
+	return out
+}
+
+func mapLongShort(d []longShortRatioDTO, period, ratioType string) []entity.LongShortRatio {
+	out := make([]entity.LongShortRatio, 0, len(d))
+	for _, x := range d {
+		longVal := x.LongAccount
+		shortVal := x.ShortAccount
+		if ratioType == entity.RatioTypeTopTraderPosition {
+			longVal = x.LongPosition
+			shortVal = x.ShortPosition
+		}
+		out = append(out, entity.LongShortRatio{
+			Source:         sourceName,
+			Symbol:         x.Symbol,
+			Period:         period,
+			RatioType:      ratioType,
+			Timestamp:      x.Timestamp,
+			LongShortRatio: x.LongShortRatio,
+			LongValue:      longVal,
+			ShortValue:     shortVal,
+		})
+	}
+	return out
+}
+
+func mapTakerVolume(d []takerVolumeDTO, symbol, period string) []entity.TakerBuySellVolume {
+	out := make([]entity.TakerBuySellVolume, 0, len(d))
+	for _, x := range d {
+		out = append(out, entity.TakerBuySellVolume{
+			Source:       sourceName,
+			Symbol:       symbol,
+			Period:       period,
+			Timestamp:    x.Timestamp,
+			BuySellRatio: x.BuySellRatio,
+			BuyVolume:    x.BuyVol,
+			SellVolume:   x.SellVol,
+		})
+	}
+	return out
+}

internal/repo/webapi/binance/market.go

@@ -0,0 +1,57 @@
+package binance
+
+import (
+	"context"
+	"net/url"
+	"strconv"
+
+	"cryptoHermes/internal/entity"
+)
+
+func (c *Client) GetKlines(ctx context.Context, symbol, interval string, limit int) ([]entity.Kline, error) {
+	return c.GetKlinesRange(ctx, symbol, interval, 0, 0, limit)
+}
+
+func (c *Client) GetKlinesRange(ctx context.Context, symbol, interval string, startMs, endMs int64, limit int) ([]entity.Kline, error) {
+	if limit <= 0 {
+		limit = 500
+	}
+	if limit > 1500 {
+		limit = 1500
+	}
+	q := url.Values{}
+	q.Set("symbol", symbol)
+	q.Set("interval", interval)
+	q.Set("limit", strconv.Itoa(limit))
+	if startMs > 0 {
+		q.Set("startTime", strconv.FormatInt(startMs, 10))
+	}
+	if endMs > 0 {
+		q.Set("endTime", strconv.FormatInt(endMs, 10))
+	}
+
+	var raw [][]any
+	if err := c.get(ctx, "/fapi/v1/klines", q, &raw); err != nil {
+		return nil, err
+	}
+
+	out := make([]entity.Kline, 0, len(raw))
+	for _, row := range raw {
+		k, err := parseKlineRow(symbol, interval, row)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, k)
+	}
+	return out, nil
+}
+
+func (c *Client) GetTicker24h(ctx context.Context, symbol string) (*entity.Ticker24h, error) {
+	q := url.Values{}
+	q.Set("symbol", symbol)
+	var dto tickerDTO
+	if err := c.get(ctx, "/fapi/v1/ticker/24hr", q, &dto); err != nil {
+		return nil, err
+	}
+	return mapTicker(&dto), nil
+}