Developer & Integration Docs

Overview

Split Finance exposes three surfaces for integrators:

• Smart contracts — on-chain staking, pairing, and vault accounting
• REST API — market metadata, pool state, APY history
• WebSocket feed — real-time pool imbalance and yield ticks

All endpoints return JSON. Authentication is via EIP-4361 (Sign-In With Ethereum) for user-scoped endpoints and API keys for server-to-server integration.

Authentication

User sessions

POST /auth/nonce
{ "address": "0xabc..." }

→ { "nonce": "a3f9...", "expires_at": 1735689600 }

POST /auth/verify
{ "address": "0xabc...", "signature": "0xdef..." }

→ { "token": "eyJ...", "expires_in": 3600 }

Server-to-server

Include the header X-Split-Key: sk_live_... on all requests. Keys are scoped to read or read-write. Rotate every 90 days.

Markets

List all markets with active staking pools.

{
  "markets": [
    {
      "id": "poly_0x9f...",
      "venue": "polymarket",
      "question": "Will X happen by Y date?",
      "yes_price": 0.72,
      "no_price": 0.28,
      "resolves_at": "2027-03-15T00:00:00Z",
      "pool": {
        "yes_staked": "125000.00",
        "no_staked": "98000.00",
        "imbalance": 0.24,
        "current_apy": 6.85,
        "boost_apy": 1.00
      }
    }
  ]
}

Retrieve a single market with full pool detail and APY history.

Returns daily APY samples over the last 90 days.

Staking

Preview the effect of a proposed stake before signing.

{
  "market_id": "poly_0x9f...",
  "side": "yes",
  "amount": "1000.00"
}

→ {
  "expected_apy": 6.85,
  "boost_applied": 0.0,
  "matched_immediately": true,
  "receipt_token": "sYES-0x9f..."
}

Returns an unsigned transaction payload to submit via the user's wallet.

List all open staking positions for an address.

Build an unstake transaction. Subject to counterparty liquidity availability.

Yield

Current accrued yield for a given address, broken down by position.

Current allocation and realized APY per underlying lending strategy.

WebSocket

wss://api.split.finance/v1/stream

// subscribe
{ "action": "subscribe", "channel": "market:poly_0x9f..." }

// messages
{ "type": "pool_update", "yes": "125100", "no": "98100", "apy": 6.86 }
{ "type": "yield_tick", "address": "0xabc...", "accrued": "0.0412" }

Smart Contracts

Contract	Address (mainnet)	Purpose
StakingVault	0x…	Deposits and receipt issuance
PairingEngine	0x…	Matches YES/NO stakers
YieldRouter	0x…	Allocates collateral to strategies
OracleAdapter	0x…	Verifies signed yield updates
TreasuryVault	0x…	Holds reserve for APY floor subsidy

Key interfaces

interface IStakingVault {
    function stake(uint256 marketId, bool side, uint256 amount) external returns (uint256 receiptId);
    function unstake(uint256 receiptId, uint256 amount) external;
    function claimYield(uint256 receiptId) external returns (uint256 yieldAmount);
}

interface IPairingEngine {
    function match(uint256 marketId) external returns (bool matched);
    function imbalance(uint256 marketId) external view returns (int256);
}

Error Codes

Code	Meaning	Resolution
4001	Insufficient counterparty liquidity	Retry later or accept longer match time
4002	Market not accepting stakes	Check resolves_at — near-resolution markets close
4003	Oracle signature invalid	Yield update rejected; no state change
4004	Stake below minimum	Minimum is 50 USDC notional per position
5001	Strategy withdrawal delayed	Lending market utilization high; queued

Rate Limits

Public endpoints: 60 req/min per IP. Authenticated: 600 req/min per key. WebSocket: 100 concurrent subscriptions per connection.

Support

Integration questions: dev@split.finance
Bug reports: github.com/split-finance