Quickstart

import {
  Wallet, JsonRpcProvider, Contract, MaxUint256,
  parseUnits, parseEther, randomBytes,
} from 'ethers';

const RPC  = 'https://rpc.ab.testnet.adifoundation.ai/';
const BASE = 'https://core.api.dev.predictstreet.sde.adifoundation.ai';

// Load both secrets from your secrets manager.
const API_KEY = process.env.PS_API_KEY!;            // ps_live_<keyId>_<secret>
const eoaPk   = process.env.PS_ASSOCIATED_WALLET_PK!;

// Canonical testnet addresses (chainId 99999)
const VAULT_FACTORY = '0x298F4D974a0715a8e9085EE3f48a14A421bCF5B6';
const USDC          = '0x979696A1B62d4c0F0390124447c065798ee4c70c';
const CTF_EXCHANGE          = '0x4074c225b296E1E556c565B0C3Ddba305E63E7c4'; // binary markets
const CTF_EXCHANGE_NEG_RISK = '0x2eB97912c333963a21410Af1eF7E9a0aAB7631bf'; // neg-risk markets (negRiskEligible: true)

const provider = new JsonRpcProvider(RPC);
const eoa      = new Wallet(eoaPk, provider);
console.log('associatedWallet:', eoa.address);

// Every authenticated call ships the key header. A multi-wallet partner key
// must ALSO name the wallet it acts for, on every call (`X-User-Wallet`);
// without it the API answers 401 `api_key_user_wallet_required`. A
// single-wallet key ignores the header, so it is safe to always send it.
const auth = {
  'X-Api-Key': API_KEY,
  'X-User-Wallet': eoa.address,
  'Content-Type': 'application/json',
};

const usdc = new Contract(
  USDC,
  [
    'function mint(address,uint256)',
    'function balanceOf(address) view returns (uint256)',
    'function approve(address,uint256) returns (bool)',
  ],
  eoa,
);

await (await usdc.mint(eoa.address, parseUnits('1000', 6))).wait();
console.log('USDC balance:', (await usdc.balanceOf(eoa.address)).toString());

async function waitForVault(timeoutMs = 60_000) {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    const r = await fetch(`${BASE}/api/me/vault`, { headers: auth });
    const me = await r.json();
    // Fail fast on an auth / request error instead of polling it for 60s
    // (e.g. 401 api_key_user_wallet_required: X-User-Wallet missing).
    if (!r.ok) throw new Error(`GET /api/me/vault ${r.status}: ${JSON.stringify(me)}`);
    // deployStatus is one of: not_started | pending | building |
    //   submitted | confirmed | skipped_existing | failed_permanent
    // See /concepts/vaults/auto-deploy#deploystatus-values for
    // semantics. `deployed: true` means VaultFactory.vaultOf(eoa)
    // returns a non-zero address on chain.
    if (me.deployed) return me.vaultAddress;
    await new Promise(r => setTimeout(r, 1500));
  }
  throw new Error('vault not auto-deployed within 60s — see /concepts/vaults/auto-deploy');
}

const vault = await waitForVault();
console.log('your vault:', vault);

// One-time MaxUint256 approval is the standard pattern — saves gas
// on every future deposit. Tighten if your security model needs it.
await (await usdc.approve(vault, MaxUint256, { gasLimit: 100_000n })).wait();

const v = new Contract(
  vault,
  ['function depositERC20(address token, uint256 amount)'],
  eoa,
);
await (await v.depositERC20(
  USDC,
  parseUnits('500', 6),               // 500 USDC into the vault
  { gasLimit: 600_000n },
)).wait();

// verifyingContract depends on the market — see the Warning above.
const domainFor = (negRisk: boolean) => ({
  name: 'PredictStreet', version: '1', chainId: 99999,
  verifyingContract: negRisk ? CTF_EXCHANGE_NEG_RISK : CTF_EXCHANGE,
});
const TYPES = { Order: [
  { name: 'salt',          type: 'uint256' },
  { name: 'maker',         type: 'address' },
  { name: 'signer',        type: 'address' },
  { name: 'taker',         type: 'address' },
  { name: 'tokenId',       type: 'uint256' },
  { name: 'makerAmount',   type: 'uint256' },
  { name: 'takerAmount',   type: 'uint256' },
  { name: 'expiration',    type: 'uint256' },
  { name: 'feeRateBps',    type: 'uint256' },
  { name: 'side',          type: 'uint8'   },
  { name: 'signatureType', type: 'uint8'   },
]};

async function signOrder(opts: {
  side: 'buy' | 'sell',
  price: string,                 // e.g. "0.42" — decimal USDC
  qty: string,                   // e.g. "10"   — decimal outcome qty
  tokenId: string,               // from market.yesTokenId / market.noTokenId
  feeTakerBps: number,           // from market.feeTakerBps — see below
  negRisk: boolean,              // from market.negRiskEligible
}) {
  const priceWei    = parseUnits(opts.price, 6);
  const qtyWei      = parseUnits(opts.qty,   6);
  // BUY notional rounds UP, SELL notional rounds DOWN. A BUY signed with a
  // rounded-down notional is rejected with code order_signed_with_floor_notional.
  const product     = priceWei * qtyWei;
  const notionalWei = opts.side === 'buy'
    ? (product + 999_999n) / 1_000_000n
    : product / 1_000_000n;
  const salt        = BigInt('0x' + Buffer.from(randomBytes(32)).toString('hex'));

  const struct = {
    salt,
    maker:        vault,                                // your vault
    signer:       eoa.address,                          // your EOA
    taker:        '0x0000000000000000000000000000000000000000',
    tokenId:      BigInt(opts.tokenId),
    makerAmount:  opts.side === 'buy' ? notionalWei : qtyWei,
    takerAmount:  opts.side === 'buy' ? qtyWei      : notionalWei,
    expiration:   0n,                                   // 0 = no on-chain expiry (recommended)
    // CRITICAL: must equal `market.feeTakerBps` returned by
    // GET /api/markets/{slug} (root market lookup is slug-keyed
    // since 2026-05-16; sub-resources still take symbol). The
    // platform reconstructs the canonical Order with the live
    // market fee and recovers the signer against THAT digest —
    // signing with 0n produces a hash mismatch and `POST
    // /api/orders/place` rejects every order with `bad_signature`.
    // See `Pull a real tokenId` below for where this comes from.
    feeRateBps:   BigInt(opts.feeTakerBps),
    side:         opts.side === 'buy' ? 0 : 1,
    signatureType: 1,                                   // VAULT
  };
  const signature = await eoa.signTypedData(domainFor(opts.negRisk), TYPES, struct);
  return { struct, signature };
}

// Step 1 — pick an OPEN market from the list endpoint. It returns
// `{ markets, hasMore }`, 50 rows per page by default (page on with
// `&offset=`). Each row carries `symbol` — the `marketId` in order and
// split bodies, also accepted by sub-resource endpoints like
// `/orderbook` — and `slug`, the canonical, URL-safe identifier
// required by the root /api/markets/{slug} lookup. Step 5's split body
// is the binary-market form, so pick a binary market here.
const list = await fetch(`${BASE}/api/markets?status=OPEN`).then(r => r.json());
const target = list.markets.find(m => m.negRiskEligible === false);
if (!target) throw new Error('no OPEN binary market on this page — page on with &offset=');
const MARKET_ID = target.symbol;
const slug = target.slug;

// Step 2 — fetch market detail by slug.
const market = await fetch(
  `${BASE}/api/markets/${encodeURIComponent(slug)}`,
).then(r => r.json());

const yesTokenId  = market.yesTokenId;    // outcome '0'
const noTokenId   = market.noTokenId;     // outcome '1'
const feeTakerBps = market.feeTakerBps;   // CRITICAL — pass into signOrder
const negRisk     = market.negRiskEligible === true; // picks the signing domain

const { struct, signature } = await signOrder({
  side: 'buy', price: '0.45', qty: '10', tokenId: yesTokenId, feeTakerBps, negRisk,
});

const resp = await fetch(`${BASE}/api/orders/place`, {
  method: 'POST',
  headers: auth,
  body: JSON.stringify({
    marketId:      MARKET_ID,
    side:          'buy',
    outcome:       '0',                      // YES
    price:         '0.45',
    quantity:      '10',
    nonce:         struct.salt.toString(),
    expiry:        0,                        // = struct.expiration
    maker:         vault,                    // = struct.maker
    signature,
    type:          'limit',                  // (default — can be omitted)
    timeInForce:   'gtc',                    // (default for limit — can be omitted)
    clientOrderId: `bot-${Date.now()}`,
  }),
}).then(r => r.json());

console.log(resp);
// { orderId, status: 'PENDING' | 'OPEN' | 'FILLED' | 'CANCELLED' | 'REJECTED' | 'EXPIRED' | 'SETTLEMENT_FAILED',
//   filledQty, remainingQty, trades: [...], code?, message?, details?, clientOrderId?, traceId? }
// This response never reports PARTIAL: a partially filled resting order is 'OPEN' with filledQty > 0.

const { struct, signature } = await signOrder({
  side: 'buy', price: '0.99', qty: '5', tokenId: yesTokenId, feeTakerBps, negRisk,
});

const resp = await fetch(`${BASE}/api/orders/place`, {
  method: 'POST',
  headers: auth,
  body: JSON.stringify({
    marketId: MARKET_ID, side: 'buy', outcome: '0',
    price: '0.99', quantity: '5',
    nonce: struct.salt.toString(), expiry: 0, maker: vault, signature,
    type: 'market',
    timeInForce: 'ioc',                      // 'fok' is accepted but fills like 'ioc'
  }),
}).then(r => r.json());

// Single
await fetch(`${BASE}/api/orders/cancel`, {
  method: 'POST',
  headers: auth,
  body:    JSON.stringify({ orderId: resp.orderId }),
});

// Everything you have open
await fetch(`${BASE}/api/orders/cancel-all`, {
  method:  'POST',
  headers: auth,
  body:    '{}',
});

// 1. Get the backend co-signature
const sig = await fetch(`${BASE}/api/vault/split-signature`, {
  method:  'POST',
  headers: auth,
  body:    JSON.stringify({ marketId: MARKET_ID, amount: '50' }),
}).then(r => r.json());

// 2. Sign the same SplitPosition struct yourself
const SPLIT_TYPES = { SplitPosition: [
  { name: 'kind',            type: 'uint8'    },
  { name: 'collateralToken', type: 'address'  },
  { name: 'conditionId',     type: 'bytes32'  },
  { name: 'partition',       type: 'uint256[]' },
  { name: 'amount',          type: 'uint256'  },
  { name: 'salt',            type: 'uint256'  },
  { name: 'deadline',        type: 'uint256'  },
]};

const split = {
  kind:            sig.kind,
  collateralToken: sig.collateralToken,
  conditionId:     sig.conditionId,
  partition:       sig.partition.map(BigInt),
  amount:          BigInt(sig.amount),
  salt:            BigInt(sig.salt),
  deadline:        BigInt(sig.deadline),
};
const ownerSig = await eoa.signTypedData(
  { name: 'PredictStreetVault', version: '1', chainId: 99999, verifyingContract: vault },
  SPLIT_TYPES,
  split,
);

// 3. Submit on-chain
const vaultC = new Contract(
  vault,
  ['function splitPosition(uint8,address,bytes32,uint256[],uint256,uint256,uint256,bytes,bytes)'],
  eoa,
);
await (await vaultC.splitPosition(
  split.kind, split.collateralToken, split.conditionId,
  split.partition, split.amount, split.salt, split.deadline,
  ownerSig, sig.backendSig,
  { gasLimit: 1_500_000n },
)).wait();

const { struct, signature } = await signOrder({
  side: 'sell', price: '0.55', qty: '20', tokenId: yesTokenId, feeTakerBps, negRisk,
});

await fetch(`${BASE}/api/orders/place`, {
  method: 'POST',
  headers: auth,
  body: JSON.stringify({
    marketId: MARKET_ID, side: 'sell', outcome: '0',
    price: '0.55', quantity: '20',
    nonce: struct.salt.toString(), expiry: 0, maker: vault, signature,
  }),
});

// On-chain
const usdcInVault = await usdc.balanceOf(vault);

// Off-chain (the platform mirrors on-chain state with ~1-block lag)
const balances = await fetch(`${BASE}/api/me/balances`, {
  headers: auth,
}).then(r => r.json());

const positions = await fetch(`${BASE}/api/me/positions`, {
  headers: auth,
}).then(r => r.json());

const open = await fetch(`${BASE}/api/orders/open`, {
  headers: auth,
}).then(r => r.json());