👨‍💻Developer Integration

This guide provides the contract addresses and interfaces needed to integrate with Stimpak Duels programmatically.

Contract Addresses

Arbitrum Mainnet (Chain ID: 42161)

Contract	Address
CompetitionHub	0xF439c778446A3875Bb1583fCeDaD4873533fB5EA
CompetitionAdmin	0x3804698cCA04cf09F325901Ae92783C41b29801c
Settings	0x25F8cD7bBC8102b7Ac29B7d9f29fDf8F3D4bD334
Reader	0x36553D6b996690737c8a239D26e6204284863692
USDC	0xaf88d065e77c8cC2239327C5EDb3A432268e5831

Arbitrum Sepolia Testnet (Chain ID: 421614)

Contract	Address
CompetitionHub	0xd973D63fcd543e634A24fFB6B4392A1C618A0ff0
CompetitionAdmin	0xEC3De72e28088C82E6c6aF95E6f7A48B47C351dC
Settings	0xA950098AC296BDedb66c188755F37A243Fde89c9
Reader	0x3a12bf16809DC8ab9e2B4dA2835f48840e3090d1
USDC	0x3253a335E7bFfB4790Aa4C25C4250d206E9b9773

Supported Markets

Arbitrum Mainnet

Market	Address	Max Leverage
BTC/USD	0x47c031236e19d024b42f8AE6780E44A573170703	100x
ETH/USD	0x70d95587d40A2caf56bd97485aB3Eec10Bee6336	100x
SOL/USD	0x09400D9DB990D5ed3f35D7be61DfAEB900Af03C9	100x
LINK/USD	0x7f1fa204bb700853D36994DA19F830b6Ad18455C	100x

Arbitrum Sepolia

Market	Address	Max Leverage
BTC/USD	0x3A83246bDDD60c4e71c91c10D9A66Fd64399bBCf	100x
ETH/USD	0xb6fC4C9eB02C35A134044526C62bb15014Ac0Bcc	50x

---

Core Interfaces

Creating a Duel

Duels are created through the CompetitionHub contract. There are two types:

1. Head-to-Head (H2H) Duel

function proposeH2HCompetition(
    address _market,              // GMX market address (e.g., BTC/USD)
    uint256 _collateralAmount,    // Starting balance in USDC (6 decimals)
    uint256 _buyInAmount,         // Entry fee in USDC (6 decimals)
    address _buyInToken,          // USDC address
    uint256 _buffer,              // Buffer time before duel starts (seconds)
    uint256 _duration,            // Duel duration (seconds)
    uint256 _expirationDuration,  // Time for opponent to accept (seconds)
    bool _isProtected,            // If true, requires signature to join
    uint256 _signatureExpiration, // Signature expiration timestamp
    bytes memory _signature,      // Backend signature for validation
    bytes32 _title                // Optional title (bytes32)
) external returns (uint256 competitionId)

2. Deathmatch (Multi-player)

function createDeathmatchCompetition(
    address _market,              // GMX market address
    uint256 _collateralAmount,    // Starting balance per trader (USDC, 6 decimals)
    uint256 _buyInAmount,         // Entry fee (USDC, 6 decimals)
    address _buyInToken,          // USDC address
    uint256 _startTime,           // Unix timestamp when duel starts
    uint256 _endTime,             // Unix timestamp when duel ends
    uint256 _minParticipants,     // Minimum players needed (or cancelled)
    uint256 _maxParticipants,     // Maximum players allowed
    bool _isProtected,            // If true, requires signature to join
    uint256 _signatureExpiration, // Signature expiration timestamp
    bytes memory _signature,      // Backend signature
    bytes32 _title                // Optional title
) external returns (uint256 competitionId)

---

Joining a Duel

function joinCompetition(
    uint256 _competitionId,       // ID of the competition to join
    uint256 _expiration,          // Signature expiration timestamp
    bytes memory _signature       // Backend signature for validation
) external

Note: Before joining, users must approve the CompetitionHub to spend their USDC:

// Approve buy-in amount + collateral amount
IERC20(usdcAddress).approve(competitionHubAddress, buyInAmount + collateralAmount);

---

Trading in a Duel

Once joined, each participant gets a Trader contract deployed for them. Trading is done through this contract.

Open a Position

function openPosition(
    uint256 collateralAmountUsdc, // Collateral to use (USDC, 6 decimals)
    uint256 _acceptablePrice,     // Max/min acceptable price (30 decimals)
    uint256 _size,                // Position size in USD (30 decimals)
    uint256 _collateral,          // Collateral for the position
    bool _isLong,                 // true = long, false = short
    uint256 _triggerPrice         // Trigger price for limit orders (0 for market)
) external payable

Close a Position

function closePosition(
    uint256 _acceptablePrice,     // Acceptable execution price (30 decimals)
    uint256 _sizeDelta,           // Size to close (30 decimals, use position size for full close)
    bool _isLong,                 // Position direction
    uint256 _triggerPrice         // 0 for market order
) external payable

Cancel an Order

function cancelOrder(
    bytes32 _orderKey             // The order key to cancel
) external payable

Note: Trading functions require ETH for GMX execution fees (typically 0.0001-0.001 ETH).

---

Reading Duel Data

Get Competition Data

function getCompetitionData(uint256 competitionId) external view returns (
    bool isHeadToHead,
    bool isProtected,
    uint8 status,                 // 0=Awaiting, 1=Registration, 2=Active, 3=Ended, 4=Finalized, 5=Cancelled
    address market,
    uint256 startTime,
    uint256 endTime,
    uint256 buyInAmount,
    address buyInToken,
    uint256 collateralAmount,
    uint256 prizePool,
    uint256 platformFeePool,
    uint256 sponsorshipPool,
    uint256 minParticipants,
    uint256 maxParticipants,
    address winner
)

Get Participant's Trader Contract

function getTraderContract(
    uint256 _competitionId,
    address _participant
) external view returns (address traderContract)

---

Competition Status Codes

Status	Value	Description
Awaiting Opponent	0	H2H waiting for opponent
Registration Open	1	Deathmatch accepting entries
Active	2	Trading is live
Ended	3	Trading complete, awaiting finalization
Finalized	4	Winner determined, prizes distributed
Cancelled	5	Duel cancelled, refunds available
Elapsed	6	Expired without sufficient participants
No Contest	7	Ended with no valid trades

---

Example Integration (ethers.js v6)

import { ethers } from 'ethers';

// Contract ABIs (simplified - full ABIs available in our GitHub)
const COMPETITION_HUB_ABI = [
  'function joinCompetition(uint256 _competitionId, uint256 _expiration, bytes memory _signature) external',
  'function getCompetitionData(uint256 competitionId) external view returns (bool, bool, uint8, address, uint256, uint256, uint256, address, uint256, uint256, uint256, uint256, uint256, uint256, address)',
  'function getTraderContract(uint256 _competitionId, address _participant) external view returns (address)'
];

const TRADER_ABI = [
  'function openPosition(uint256 collateralAmountUsdc, uint256 _acceptablePrice, uint256 _size, uint256 _collateral, bool _isLong, uint256 _triggerPrice) external payable',
  'function closePosition(uint256 _acceptablePrice, uint256 _sizeDelta, bool _isLong, uint256 _triggerPrice) external payable',
  'function availableAmount() external view returns (uint256)'
];

const ERC20_ABI = [
  'function approve(address spender, uint256 amount) external returns (bool)',
  'function allowance(address owner, address spender) external view returns (uint256)'
];

// Addresses (Arbitrum Mainnet)
const COMPETITION_HUB = '0xF439c778446A3875Bb1583fCeDaD4873533fB5EA';
const USDC = '0xaf88d065e77c8cC2239327C5EDb3A432268e5831';

async function joinDuel(signer: ethers.Signer, competitionId: number, signature: string, expiration: number) {
  const hub = new ethers.Contract(COMPETITION_HUB, COMPETITION_HUB_ABI, signer);
  const usdc = new ethers.Contract(USDC, ERC20_ABI, signer);
  
  // Get competition data to know approval amount
  const data = await hub.getCompetitionData(competitionId);
  const buyInAmount = data[6];  // buyInAmount
  const collateral = data[8];   // collateralAmount
  const totalAmount = buyInAmount + collateral;
  
  // Approve USDC spend
  const allowance = await usdc.allowance(await signer.getAddress(), COMPETITION_HUB);
  if (allowance < totalAmount) {
    const approveTx = await usdc.approve(COMPETITION_HUB, totalAmount);
    await approveTx.wait();
  }
  
  // Join the competition
  const joinTx = await hub.joinCompetition(competitionId, expiration, signature);
  await joinTx.wait();
  
  return joinTx.hash;
}

async function openLongPosition(signer: ethers.Signer, competitionId: number, sizeUsd: bigint) {
  const hub = new ethers.Contract(COMPETITION_HUB, COMPETITION_HUB_ABI, signer);
  const userAddress = await signer.getAddress();
  
  // Get the user's trader contract
  const traderAddress = await hub.getTraderContract(competitionId, userAddress);
  const trader = new ethers.Contract(traderAddress, TRADER_ABI, signer);
  
  // Get available collateral
  const available = await trader.availableAmount();
  
  // Open a long position with market order
  // Using 1% slippage on acceptable price (you'd fetch current price from GMX)
  const acceptablePrice = ethers.parseUnits('100000', 30); // Example: $100k BTC price with 30 decimals
  const executionFee = ethers.parseEther('0.0003'); // GMX execution fee
  
  const tx = await trader.openPosition(
    available,           // Use full available collateral
    acceptablePrice,     // Acceptable price (30 decimals)
    sizeUsd,             // Position size (30 decimals)
    available,           // Collateral amount
    true,                // isLong
    0,                   // triggerPrice (0 for market order)
    { value: executionFee }
  );
  
  await tx.wait();
  return tx.hash;
}

---

Signature Requirements

All duel creation and joining requires a backend signature for validation. Contact the Stimpak team for API access to obtain signatures programmatically.

Signature Format

The signature validates:

• User address

• Competition parameters

• Nonce (to prevent replay attacks)

• Expiration timestamp

---

Resources

• Subgraph (Mainnet): api.goldsky.com/.../stimpak-duels-mainnet/1.0.0/gn

• Subgraph (Testnet): api.goldsky.com/.../stimpak-duels-testnet/1.0.0/gn

• Discord: Join our developer community for support

---

Events to Listen For

// Competition lifecycle
event CompetitionCreated(uint256 indexed competitionId, bool isHeadToHead, bool isProtected, address indexed proposer);
event CompetitionJoined(uint256 indexed competitionId, address participant);
event CompetitionStarted(uint256 indexed competitionId);
event CompetitionFinalized(uint256 indexed competitionId, address winner, bool isCancelled);

// Trading events (from Trader contract)
event TradeExecuted(bytes32 indexed orderKey, bool isLong, uint256 sizeDelta, uint256 executionPrice);
event PositionOpened(bytes32 indexed orderKey, bool isLong, uint256 size, uint256 collateral);
event PositionClosed(bytes32 indexed orderKey, uint256 realizedPnl);