Instruments and money on the wire

# Lists instruments and prints the six values you need before ordering.
# PolymarketClient is the canonical auth client published on /connect#authentication:
# it mints a private_key_jwt access token and refreshes on expires_in minus 30 seconds.
from polymarket_auth import PolymarketClient

# Generated from polymarket-protos.zip. VERIFY your own package path.
from polymarket.v1 import refdata_pb2, refdata_pb2_grpc

# The gRPC target is GRPC_TARGET in polymarket_auth.py — one place, both environments.
pmx = PolymarketClient()

with pmx.channel() as ch:
    stub = refdata_pb2_grpc.ReferenceDataAPIStub(ch)
    # ListInstruments is capped at 6 requests/min. Page, cache, do not poll.
    # /v1/refdata/* is not account-scoped: no x-participant-id.
    resp = stub.ListInstruments(refdata_pb2.ListInstrumentsRequest(), metadata=pmx.metadata())

for inst in resp.instruments:
    # Both scales are multipliers. One dollar is price_scale * fractional_quantity_scale units.
    print(
        inst.symbol,
        inst.price_scale,                 # 100 on most instruments, 1000 on some
        inst.fractional_quantity_scale,   # 100 on most instruments, 1 on some
        inst.state,
    )

// Lists instruments and prints the six values you need before ordering.
// PolymarketClient is the canonical auth client published on /connect#authentication.
import { PolymarketClient } from "./polymarketAuth";

// Generated from polymarket-protos.zip. VERIFY your own package path.
import { ReferenceDataAPIClient } from "./gen/polymarket/v1/refdata";

// The gRPC target is GRPC_TARGET in polymarketAuth.ts — one place, both environments.
const pmx = new PolymarketClient();

const client = new ReferenceDataAPIClient(pmx.channel());

// ListInstruments is capped at 6 requests/min. Page, cache, do not poll.
// /v1/refdata/* is not account-scoped: no x-participant-id.
const resp = await client.listInstruments({}, await pmx.metadata());

for (const inst of resp.instruments) {
  // Both scales are multipliers. One dollar is priceScale * fractionalQtyScale units.
  console.log(
    inst.symbol,
    inst.priceScale,          // 100 on most instruments, 1000 on some
    inst.fractionalQtyScale,  // 100 on most instruments, 1 on some
    inst.state,
  );
}

# curl cannot speak gRPC. Use grpcurl.
# Server reflection is entitlement-gated and returns
#   PermissionDenied: method not permitted
# without the grant, so pass the protos explicitly rather than relying on -use-reflection.
TOKEN="$(./token.sh)"   # token.sh is published on /connect#authentication; stdout is the token

grpcurl \
  -import-path ./polymarket-protos \
  -proto polymarket/v1/refdata.proto \
  -H "authorization: Bearer ${TOKEN}" \
  -d '{}' \
  grpc-api.preprod.polymarketexchange.com:443 \
  polymarket.v1.ReferenceDataAPI/ListInstruments \
  || { echo "ListInstruments failed"; exit 1; }

// Lists instruments and prints the six values you need before ordering.
package main

import (
	"context"
	"fmt"
	"log"

	"google.golang.org/grpc/metadata"

	// Canonical auth client from /connect#authentication. The gRPC target is
	// pmauth.GRPCTarget — one place, both environments.
	pmauth "example.com/yourfirm/pmauth"

	// Generated from polymarket-protos.zip. VERIFY your own package path.
	refdata "github.com/yourfirm/gen/polymarket/v1"
)

func main() {
	ctx := context.Background()
	pm := pmauth.New()

	conn, err := pm.Channel()
	if err != nil {
		log.Fatalf("dial: %v", err)
	}
	defer conn.Close()

	// /v1/refdata/* is not account-scoped: pass "" for the participant ID.
	md, err := pm.Metadata("")
	if err != nil {
		log.Fatalf("metadata: %v", err)
	}

	// ListInstruments is capped at 6 requests/min. Page, cache, do not poll.
	resp, err := refdata.NewReferenceDataAPIClient(conn).ListInstruments(
		metadata.NewOutgoingContext(ctx, md), &refdata.ListInstrumentsRequest{})
	if err != nil {
		log.Fatalf("ListInstruments: %v", err)
	}

	for _, inst := range resp.GetInstruments() {
		// Both scales are multipliers. One dollar is PriceScale * FractionalQuantityScale units.
		fmt.Println(
			inst.GetSymbol(),
			inst.GetPriceScale(),              // 100 on most instruments, 1000 on some
			inst.GetFractionalQuantityScale(), // 100 on most instruments, 1 on some
			inst.GetState(),
		)
	}
}

# Decodes one execution report and checks the fee against the schedule.
# Exact decimal arithmetic. Never use float for money.
from decimal import Decimal, ROUND_HALF_EVEN

# Read both scales off the instrument (see #find-instruments). Never hard-code them.
PRICE_SCALE = Decimal(100)
QTY_SCALE = Decimal(100)
THETA_TAKER = Decimal("0.06")  # taker coefficient; there is no fee-schedule endpoint

# int64 fields arrive as JSON strings.
WIRE_PRICE = Decimal("32")
WIRE_QTY = Decimal("75")
WIRE_COMMISSION = Decimal("100")

if PRICE_SCALE <= 0 or QTY_SCALE <= 0:
    raise ValueError("scale absent or zero: proto3 cannot distinguish these — refuse the order")

price = WIRE_PRICE / PRICE_SCALE            # 0.32
contracts = WIRE_QTY / QTY_SCALE            # 0.75  (NOT 75)
principal = contracts * price               # 0.24
dollar_units = PRICE_SCALE * QTY_SCALE      # 10000 notional units per dollar

commission = WIRE_COMMISSION / dollar_units                  # 0.01  <- correct
commission_wrong = WIRE_COMMISSION / PRICE_SCALE             # 1.00  <- the 100x error

expected = (THETA_TAKER * contracts * price * (1 - price)).quantize(
    Decimal("0.01"), rounding=ROUND_HALF_EVEN                # banker's rounding, to the cent
)

def usd(amount: Decimal) -> str:
    return f"${amount.quantize(Decimal('0.01'), rounding=ROUND_HALF_EVEN)}"

print(f"principal={usd(principal)} fee={usd(commission)}")
print(f"reading the fee at priceScale alone would give {usd(commission_wrong)}")

if commission != expected:
    raise AssertionError(f"fee mismatch: wire {commission} vs schedule {expected}")

// Decodes one execution report and checks the fee against the schedule.
// Integer arithmetic on BigInt. Never use Number for money.

// Read both scales off the instrument (see #find-instruments). Never hard-code them.
const PRICE_SCALE = 100n;
const QTY_SCALE = 100n;
const THETA_NUM = 6n, THETA_DEN = 100n; // taker Θ = 0.06; there is no fee-schedule endpoint

// int64 fields arrive as JSON strings.
const WIRE_PRICE = BigInt("32");
const WIRE_QTY = BigInt("75");
const WIRE_COMMISSION = BigInt("100");

if (PRICE_SCALE <= 0n || QTY_SCALE <= 0n) {
  throw new Error("scale absent or zero: proto3 cannot distinguish these — refuse the order");
}

// Banker's rounding on an exact integer ratio.
function halfEven(n: bigint, d: bigint): bigint {
  let q = n / d;
  const r = n % d;
  if (2n * r > d) q += 1n;
  else if (2n * r === d && q % 2n === 1n) q += 1n;
  return q;
}
const cents = (x: bigint) => `$${(x / 100n)}.${String(x % 100n).padStart(2, "0")}`;

const DOLLAR_UNITS = PRICE_SCALE * QTY_SCALE; // 10000 notional units per dollar

// principal in cents = WIRE_QTY * WIRE_PRICE * 100 / (QTY_SCALE * PRICE_SCALE)
const principalCents = halfEven(WIRE_QTY * WIRE_PRICE * 100n, QTY_SCALE * PRICE_SCALE); // 24
const feeCents = halfEven(WIRE_COMMISSION * 100n, DOLLAR_UNITS);                        // 1
const feeCentsWrong = halfEven(WIRE_COMMISSION * 100n, PRICE_SCALE);                    // 100 = the 100x error

// Fee = Θ × C × p × (1 − p), to the cent, banker's rounding.
const expectedCents = halfEven(
  THETA_NUM * 100n * WIRE_QTY * WIRE_PRICE * (PRICE_SCALE - WIRE_PRICE),
  THETA_DEN * QTY_SCALE * PRICE_SCALE * PRICE_SCALE,
);

console.log(`principal=${cents(principalCents)} fee=${cents(feeCents)}`);
console.log(`reading the fee at priceScale alone would give ${cents(feeCentsWrong)}`);

if (feeCents !== expectedCents) {
  throw new Error(`fee mismatch: wire ${feeCents}c vs schedule ${expectedCents}c`);
}

#!/usr/bin/env bash
# Decodes one execution report and checks the fee against the schedule.
# Integer arithmetic only. bash has no decimals, which is the right constraint for money.
set -euo pipefail

# Read both scales off the instrument (see #find-instruments). Never hard-code them.
PRICE_SCALE=100
QTY_SCALE=100
THETA_NUM=6; THETA_DEN=100   # taker Θ = 0.06; there is no fee-schedule endpoint

# int64 fields arrive as JSON strings.
WIRE_PRICE=32
WIRE_QTY=75
WIRE_COMMISSION=100

(( PRICE_SCALE > 0 && QTY_SCALE > 0 )) || {
  echo "scale absent or zero: proto3 cannot distinguish these — refuse the order" >&2; exit 1; }

# Banker's rounding on an exact integer ratio.
half_even() {
  local n=$1 d=$2 q r
  q=$(( n / d )); r=$(( n % d ))
  if   (( 2*r >  d ));                    then q=$(( q + 1 ))
  elif (( 2*r == d && q % 2 == 1 ));      then q=$(( q + 1 ))
  fi
  echo "$q"
}
show() { printf '$%d.%02d' $(( $1 / 100 )) $(( $1 % 100 )); }

DOLLAR_UNITS=$(( PRICE_SCALE * QTY_SCALE ))   # 10000 notional units per dollar

PRINCIPAL_C=$(half_even $(( WIRE_QTY * WIRE_PRICE * 100 )) $(( QTY_SCALE * PRICE_SCALE )))  # 24
FEE_C=$(half_even       $(( WIRE_COMMISSION * 100 ))       "$DOLLAR_UNITS")                 # 1
FEE_C_WRONG=$(half_even $(( WIRE_COMMISSION * 100 ))       "$PRICE_SCALE")                  # 100

# Fee = Θ × C × p × (1 − p), to the cent, banker's rounding.
EXPECTED_C=$(half_even \
  $(( THETA_NUM * 100 * WIRE_QTY * WIRE_PRICE * (PRICE_SCALE - WIRE_PRICE) )) \
  $(( THETA_DEN * QTY_SCALE * PRICE_SCALE * PRICE_SCALE )) )

echo "principal=$(show "$PRINCIPAL_C") fee=$(show "$FEE_C")"
echo "reading the fee at priceScale alone would give $(show "$FEE_C_WRONG")"

(( FEE_C == EXPECTED_C )) || { echo "fee mismatch: $FEE_C vs $EXPECTED_C" >&2; exit 1; }

// Decodes one execution report and checks the fee against the schedule.
// Integer arithmetic on int64. Never use float64 for money.
package main

import (
	"fmt"
	"log"
	"strconv"
)

// Read both scales off the instrument (see #find-instruments). Never hard-code them.
const (
	priceScale = int64(100)
	qtyScale   = int64(100)
	thetaNum   = int64(6) // taker Θ = 0.06; there is no fee-schedule endpoint
	thetaDen   = int64(100)
)

// halfEven divides n by d with banker's rounding.
func halfEven(n, d int64) int64 {
	q, r := n/d, n%d
	switch {
	case 2*r > d:
		q++
	case 2*r == d && q%2 == 1:
		q++
	}
	return q
}

func show(cents int64) string { return fmt.Sprintf("$%d.%02d", cents/100, cents%100) }

func main() {
	// int64 fields arrive as JSON strings.
	wirePrice, err := strconv.ParseInt("32", 10, 64)
	if err != nil {
		log.Fatalf("price: %v", err)
	}
	wireQty, err := strconv.ParseInt("75", 10, 64)
	if err != nil {
		log.Fatalf("order_qty: %v", err)
	}
	wireCommission, err := strconv.ParseInt("100", 10, 64)
	if err != nil {
		log.Fatalf("commission_notional_collected: %v", err)
	}

	if priceScale <= 0 || qtyScale <= 0 {
		log.Fatal("scale absent or zero: proto3 cannot distinguish these — refuse the order")
	}

	dollarUnits := priceScale * qtyScale // 10000 notional units per dollar

	principalC := halfEven(wireQty*wirePrice*100, qtyScale*priceScale) // 24
	feeC := halfEven(wireCommission*100, dollarUnits)                  // 1
	feeCWrong := halfEven(wireCommission*100, priceScale)              // 100 = the 100x error

	// Fee = Θ × C × p × (1 − p), to the cent, banker's rounding.
	expectedC := halfEven(
		thetaNum*100*wireQty*wirePrice*(priceScale-wirePrice),
		thetaDen*qtyScale*priceScale*priceScale,
	)

	fmt.Printf("principal=%s fee=%s\n", show(principalC), show(feeC))
	fmt.Printf("reading the fee at priceScale alone would give %s\n", show(feeCWrong))

	if feeC != expectedC {
		log.Fatalf("fee mismatch: %dc vs schedule %dc", feeC, expectedC)
	}
}