API Documentation

Complete REST API reference for the ZipToken platform.

Base URL:https://api.ziptoken.io

Authentication

All API requests require a Bearer token in the Authorization header. Create API keys in the Institutional > Trading API section.

bash

curl https://api.ziptoken.io/api/kyc/status \
  -H "Authorization: Bearer YOUR_API_KEY"

KYC

Identity verification and compliance endpoints.

POST/api/kyc/inquiry

Create a new KYC verification inquiry.

Request Body

Name	Type	Description
tier*	'basic' \| 'enhanced' \| 'institutional'	Verification tier to apply for.

Response

json

{
  "data": {
    "status": "pending",
    "tier": "basic",
    "sanctionsCleared": false,
    "pepScreened": false,
    "adverseMediaCleared": false,
    "countryCode": null,
    "expiresAt": null,
    "limits": null
  }
}

bash

curl -X POST https://api.ziptoken.io/api/kyc/inquiry \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"tier": "basic"}'

GET/api/kyc/status

Get current KYC verification status.

Response

json

{
  "data": {
    "status": "approved",
    "tier": "enhanced",
    "sanctionsCleared": true,
    "pepScreened": true,
    "adverseMediaCleared": true,
    "countryCode": "US",
    "expiresAt": 1735689600,
    "limits": {
      "maxPosition": 100000,
      "maxDaily": 50000,
      "maxTotal": 500000
    }
  }
}

bash

curl https://api.ziptoken.io/api/kyc/status \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/kyc/limits

Get position and trading limits for the current KYC tier.

Response

json

{
  "data": {
    "maxPosition": 100000,
    "maxDaily": 50000,
    "maxTotal": 500000
  }
}

bash

curl https://api.ziptoken.io/api/kyc/limits \
  -H "Authorization: Bearer YOUR_API_KEY"

Custody

Institutional-grade wallet management via BitGo or Anchorage.

POST/api/custody/wallets

Create a new custody wallet.

Request Body

Name	Type	Description
provider*	'bitgo' \| 'anchorage'	Custody provider.
label*	string	Human-readable wallet label.
coin	string	Coin type. Defaults to USDC.

Response

json

{
  "data": {
    "id": "wallet_abc123",
    "provider": "bitgo",
    "label": "Trading Wallet",
    "coin": "usdc",
    "address": "0x1234...abcd",
    "createdAt": 1700000000
  }
}

bash

curl -X POST https://api.ziptoken.io/api/custody/wallets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"provider": "bitgo", "label": "Trading Wallet"}'

GET/api/custody/wallets

List all custody wallets.

Query Parameters

Name	Type	Description
provider	string	Filter by provider.

Response

json

{
  "data": [
    {
      "id": "wallet_abc123",
      "provider": "bitgo",
      "label": "Trading Wallet",
      "coin": "usdc",
      "address": "0x1234...abcd",
      "createdAt": 1700000000
    }
  ]
}

bash

curl https://api.ziptoken.io/api/custody/wallets \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/custody/wallets/:walletId

Get a specific wallet by ID.

Path Parameters

Name	Type	Description
walletId*	string	Wallet ID.

Response

json

{
  "data": {
    "id": "wallet_abc123",
    "provider": "bitgo",
    "label": "Trading Wallet",
    "coin": "usdc",
    "address": "0x1234...abcd",
    "createdAt": 1700000000
  }
}

bash

curl https://api.ziptoken.io/api/custody/wallets/wallet_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/custody/wallets/:walletId/balance

Get wallet balance.

Path Parameters

Name	Type	Description
walletId*	string	Wallet ID.

Response

json

{
  "data": {
    "walletId": "wallet_abc123",
    "coin": "usdc",
    "balance": "50000.00",
    "availableBalance": "48000.00"
  }
}

bash

curl https://api.ziptoken.io/api/custody/wallets/wallet_abc123/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/custody/transfers

Initiate a custody transfer.

Request Body

Name	Type	Description
walletId*	string	Source wallet ID.
destinationAddress*	string	Destination address.
amount*	string	Transfer amount.
coin	string	Coin type.
memo	string	Optional memo.

Response

json

{
  "data": {
    "id": "tx_xyz789",
    "walletId": "wallet_abc123",
    "type": "transfer",
    "amount": "1000.00",
    "coin": "usdc",
    "destinationAddress": "0xdest...addr",
    "status": "pending_approval",
    "createdAt": 1700000000
  }
}

bash

curl -X POST https://api.ziptoken.io/api/custody/transfers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"walletId": "wallet_abc123", "destinationAddress": "0xdest...addr", "amount": "1000.00"}'

GET/api/custody/wallets/:walletId/transactions

List transactions for a wallet.

Path Parameters

Name	Type	Description
walletId*	string	Wallet ID.

Query Parameters

Name	Type	Description
limit	number	Max results.
status	string	Filter by status.

Response

json

{
  "data": [
    {
      "id": "tx_xyz789",
      "walletId": "wallet_abc123",
      "type": "transfer",
      "amount": "1000.00",
      "coin": "usdc",
      "destinationAddress": "0xdest...addr",
      "status": "confirmed",
      "createdAt": 1700000000
    }
  ]
}

bash

curl "https://api.ziptoken.io/api/custody/wallets/wallet_abc123/transactions?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Trading

Programmatic order placement and management.

POST/api/trading/keys

Create a new API key for programmatic access.

Request Body

Name	Type	Description
label*	string	Key label.
permissions*	string[]	Array of permissions: read:markets, read:portfolio, create:orders, cancel:orders, read:oracle, manage:custody.
rateLimit	number	Requests per minute. Defaults to tier limit.
expiresInDays	number	Key expiry in days.

Response

json

{
  "data": {
    "id": "key_abc123",
    "label": "Trading Bot",
    "prefix": "zt_live_abc",
    "permissions": ["read:markets", "create:orders"],
    "rateLimit": 120,
    "createdAt": 1700000000,
    "lastUsed": null,
    "expiresAt": null,
    "secret": "zt_live_abc...full_secret"
  }
}

bash

curl -X POST https://api.ziptoken.io/api/trading/keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"label": "Trading Bot", "permissions": ["read:markets", "create:orders"]}'

GET/api/trading/keys

List all API keys for the account.

Response

json

{
  "data": [
    {
      "id": "key_abc123",
      "label": "Trading Bot",
      "prefix": "zt_live_abc",
      "permissions": ["read:markets", "create:orders"],
      "rateLimit": 120,
      "createdAt": 1700000000,
      "lastUsed": 1700100000,
      "expiresAt": null
    }
  ]
}

bash

curl https://api.ziptoken.io/api/trading/keys \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE/api/trading/keys/:keyId

Revoke an API key. This action is irreversible.

Path Parameters

Name	Type	Description
keyId*	string	API key ID to revoke.

Response

json

{
  "data": { "success": true }
}

bash

curl -X DELETE https://api.ziptoken.io/api/trading/keys/key_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/trading/orders

Place a single order on a prediction market.

Request Body

Name	Type	Description
marketId*	string	Market to trade on.
outcomeIndex*	number	0 = YES/first outcome, 1 = NO/second outcome.
side*	'BUY' \| 'SELL'	Order side.
amount*	string	USDC amount.
price*	number	Limit price (0.01 - 0.99).
expiry	number	Unix timestamp for order expiry.

Response

json

{
  "data": {
    "id": "order_xyz",
    "maker": "0xuser...addr",
    "marketId": "mkt_10025_price",
    "outcomeIndex": 0,
    "side": "BUY",
    "amount": "100.00",
    "price": 0.65,
    "status": "OPEN",
    "filledAmount": "0",
    "expiry": 0,
    "createdAt": 1700000000
  }
}

bash

curl -X POST https://api.ziptoken.io/api/trading/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"marketId": "mkt_10025_price", "outcomeIndex": 0, "side": "BUY", "amount": "100.00", "price": 0.65}'

POST/api/trading/orders/batch

Place multiple orders in a single atomic request.

Request Body

Name	Type	Description
orders*	Order[]	Array of order objects. Same fields as single order.

Response

json

{
  "data": [
    { "id": "order_1", "status": "OPEN", ... },
    { "id": "order_2", "status": "OPEN", ... }
  ]
}

bash

curl -X POST https://api.ziptoken.io/api/trading/orders/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"orders": [
    {"marketId": "mkt_10025_price", "outcomeIndex": 0, "side": "BUY", "amount": "50", "price": 0.60},
    {"marketId": "mkt_10036_price", "outcomeIndex": 1, "side": "BUY", "amount": "50", "price": 0.40}
  ]}'

DELETE/api/trading/orders/:orderId

Cancel a single open order.

Path Parameters

Name	Type	Description
orderId*	string	Order ID to cancel.

Response

json

{
  "data": { "success": true }
}

bash

curl -X DELETE https://api.ziptoken.io/api/trading/orders/order_xyz \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/trading/orders/cancel-all

Cancel all open orders, optionally filtered by market.

Request Body

Name	Type	Description
marketId	string	Cancel only orders for this market.

Response

json

{
  "data": { "cancelledCount": 5 }
}

bash

curl -X POST https://api.ziptoken.io/api/trading/orders/cancel-all \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"marketId": "mkt_10025_price"}'

Audit

SOC 2 compliant audit trail and integrity verification.

GET/api/audit/logs

Retrieve audit log entries with optional filters.

Query Parameters

Name	Type	Description
userId	string	Filter by user.
action	string	Filter by action type.
severity	'info' \| 'warning' \| 'critical'	Filter by severity.
limit	number	Max entries to return.
offset	number	Pagination offset.

Response

json

{
  "data": [
    {
      "id": "audit_001",
      "action": "order.placed",
      "userId": "user_abc",
      "severity": "info",
      "resource": "order_xyz",
      "details": { "marketId": "mkt_10025_price", "amount": "100.00" },
      "success": true,
      "timestamp": 1700000000,
      "hash": "sha256...",
      "previousHash": "sha256..."
    }
  ]
}

bash

curl "https://api.ziptoken.io/api/audit/logs?severity=critical&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/audit/stats

Get aggregated audit statistics.

Query Parameters

Name	Type	Description
startTime	number	Unix timestamp start.
endTime	number	Unix timestamp end.

Response

json

{
  "data": {
    "totalEvents": 12450,
    "byAction": { "order.placed": 8200, "order.cancelled": 1100, ... },
    "bySeverity": { "info": 11000, "warning": 1200, "critical": 250 },
    "timeRange": { "start": 1699000000, "end": 1700000000 }
  }
}

bash

curl "https://api.ziptoken.io/api/audit/stats?startTime=1699000000" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/audit/verify

Verify the integrity of the audit hash chain.

Response

json

{
  "data": {
    "valid": true,
    "totalEntries": 12450,
    "checkedAt": 1700000000
  }
}

bash

curl https://api.ziptoken.io/api/audit/verify \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/audit/export

Export audit logs for regulatory reporting.

Query Parameters

Name	Type	Description
startTime	number	Unix timestamp start.
endTime	number	Unix timestamp end.

Response

json

{
  "data": [ ...AuditEntry[] ]
}

bash

curl "https://api.ziptoken.io/api/audit/export?startTime=1699000000&endTime=1700000000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Contract Builder

Create custom prediction market contracts.

GET/api/contract-builder/templates

List all available contract templates.

Response

json

{
  "data": [
    {
      "id": "tpl_single_zip",
      "name": "Single Zip Code",
      "description": "Binary market on a single zip code metric.",
      "category": "basic",
      "primaryUsers": ["retail", "institutional"]
    }
  ]
}

bash

curl https://api.ziptoken.io/api/contract-builder/templates \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/contract-builder/templates/:id

Get a specific template by ID.

Path Parameters

Name	Type	Description
id*	string	Template ID.

Response

json

{
  "data": {
    "id": "tpl_single_zip",
    "name": "Single Zip Code",
    "description": "Binary market on a single zip code metric.",
    "category": "basic",
    "primaryUsers": ["retail", "institutional"]
  }
}

bash

curl https://api.ziptoken.io/api/contract-builder/templates/tpl_single_zip \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/contract-builder/market

Build a single prediction market contract.

Request Body

Name	Type	Description
zipCode*	string	Target zip code.
metricType*	string	Metric: zhvi, rental_yield, foreclosure_rate, months_of_supply, list_to_sale_ratio, construction_permits.
threshold*	number	Threshold value for binary resolution.
resolutionTimestamp*	number	Unix timestamp for resolution.

Response

json

{
  "data": {
    "zipCode": "10025",
    "metricType": "zhvi",
    "threshold": 1200000,
    "resolutionTimestamp": 1735689600,
    "question": "Will median home value in 10025 exceed $1.2M by Dec 2025?",
    "resolutionSource": "Zillow ZHVI"
  }
}

bash

curl -X POST https://api.ziptoken.io/api/contract-builder/market \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"zipCode": "10025", "metricType": "zhvi", "threshold": 1200000, "resolutionTimestamp": 1735689600}'

POST/api/contract-builder/basket

Build a basket market spanning multiple zip codes.

Request Body

Name	Type	Description
name*	string	Basket name.
zipCodes*	string[]	Array of zip codes.
metricType*	string	Metric type.
threshold*	number	Threshold value.
resolutionTimestamp*	number	Resolution timestamp.
weights	number[]	Custom weights (must sum to 1). Defaults to equal weighting.

Response

json

{
  "data": {
    "name": "Manhattan Core",
    "zipCodes": ["10001", "10002", "10003"],
    "weights": [0.34, 0.33, 0.33],
    "metricType": "zhvi",
    "threshold": 1000000,
    "resolutionTimestamp": 1735689600,
    "markets": [ ...MarketSpec[] ]
  }
}

bash

curl -X POST https://api.ziptoken.io/api/contract-builder/basket \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name": "Manhattan Core", "zipCodes": ["10001","10002","10003"], "metricType": "zhvi", "threshold": 1000000, "resolutionTimestamp": 1735689600}'

POST/api/contract-builder/portfolio-hedge

Generate a hedge bundle for a portfolio of real estate exposures.

Request Body

Name	Type	Description
exposures*	{ zipCode: string; notionalAmount: number }[]	Portfolio exposures.
metricType*	string	Primary metric.
threshold*	number	Threshold.
resolutionTimestamp*	number	Resolution date.
additionalMetrics	string[]	Extra metrics to hedge.
minBasketSize	number	Minimum zip codes per basket.

Response

json

{
  "data": {
    "exposures": [...],
    "baskets": [ ...BasketSpec[] ],
    "individualMarkets": [ ...MarketSpec[] ],
    "totalMarkets": 8
  }
}

bash

curl -X POST https://api.ziptoken.io/api/contract-builder/portfolio-hedge \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"exposures": [{"zipCode":"10025","notionalAmount":500000}], "metricType": "zhvi", "threshold": 1200000, "resolutionTimestamp": 1735689600}'

POST/api/contract-builder/from-template

Build a market from a predefined template.

Request Body

Name	Type	Description
templateId*	string	Template ID.
metricType*	string	Metric type.
resolutionTimestamp*	number	Resolution timestamp.
threshold	number	Threshold override.
exposures	{ zipCode: string; notionalAmount: number }[]	Portfolio exposures (for hedge templates).

Response

json

{
  "data": { ...MarketSpec | BasketSpec | HedgeBundle }
}

bash

curl -X POST https://api.ziptoken.io/api/contract-builder/from-template \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"templateId": "tpl_single_zip", "metricType": "zhvi", "resolutionTimestamp": 1735689600, "threshold": 1200000}'

Liquidity

Position limits, margin health, and fee estimation.

GET/api/liquidity/tiers

List all liquidity tiers.

Response

json

{
  "data": [
    {
      "tier": "standard",
      "maxPositionSize": 10000,
      "maxDailyVolume": 50000,
      "maxOpenPositions": 20,
      "marginRequirement": 0.1,
      "tradingFee": 0.01
    }
  ]
}

bash

curl https://api.ziptoken.io/api/liquidity/tiers \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/liquidity/tiers/:tier

Get a specific liquidity tier.

Path Parameters

Name	Type	Description
tier*	string	Tier name.

Response

json

{
  "data": {
    "tier": "institutional",
    "maxPositionSize": 1000000,
    "maxDailyVolume": 5000000,
    "maxOpenPositions": 500,
    "marginRequirement": 0.05,
    "tradingFee": 0.005
  }
}

bash

curl https://api.ziptoken.io/api/liquidity/tiers/institutional \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/liquidity/requirements/:metricType

Get liquidity requirements for a metric type.

Path Parameters

Name	Type	Description
metricType*	string	Metric type.

Response

json

{
  "data": {
    "minLiquidity": 5000,
    "minProviders": 3,
    "spreadMax": 0.05
  }
}

bash

curl https://api.ziptoken.io/api/liquidity/requirements/zhvi \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/liquidity/validate-position

Check if a position size is valid for a market.

Request Body

Name	Type	Description
positionSize*	number	Proposed position size in USDC.
marketId*	string	Market ID.

Response

json

{
  "data": {
    "valid": true,
    "reason": null
  }
}

bash

curl -X POST https://api.ziptoken.io/api/liquidity/validate-position \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"positionSize": 5000, "marketId": "mkt_10025_price"}'

GET/api/liquidity/margin-health

Get current margin health for the account.

Response

json

{
  "data": {
    "collateralBalance": "100000.00",
    "totalExposure": "45000.00",
    "marginHealth": 0.85,
    "frozen": false,
    "healthStatus": "healthy"
  }
}

bash

curl https://api.ziptoken.io/api/liquidity/margin-health \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/liquidity/fee-estimate

Estimate trading fees for a given amount and tier.

Query Parameters

Name	Type	Description
amount*	number	Trade amount in USDC.
tier*	string	Liquidity tier.

Response

json

{
  "data": {
    "fee": 1.00,
    "netAmount": 99.00,
    "amount": 100,
    "tier": "standard",
    "feePercent": "1.00%"
  }
}

bash

curl "https://api.ziptoken.io/api/liquidity/fee-estimate?amount=100&tier=standard" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/liquidity/alerts

Get liquidity and margin alerts.

Query Parameters

Name	Type	Description
limit	number	Max alerts to return.

Response

json

{
  "data": [
    {
      "id": "alert_001",
      "type": "margin_warning",
      "message": "Margin health dropped below 50%",
      "timestamp": 1700000000
    }
  ]
}

bash

curl "https://api.ziptoken.io/api/liquidity/alerts?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Public Data API (Agents)

Read-only data plane for AI agents, scripts, and other programmatic consumers: live index values, prediction markets, resolutions, and geo search. No wallet or KYC required -- a separate, optionally-authenticated surface from the Trading API above.

Every route below accepts an optional x-api-key header (PublicApiKeyAuth in the OpenAPI spec). Omitting it still works -- requests fall back to the unauthenticated tier (a global per-IP rate limit); passing a key just raises your limit.

Keys are issued today via an admin-guarded endpoint (see "Create a public API key" below), gated by an x-admin-secret header held by the ZipToken team -- email api@ziptoken.io for one. Self-serve key creation is planned but has not shipped yet.

Index values are derived from Zillow ZHVI data under license. Every response that carries a value includes attribution: "Data from Zillow" -- keep that string attached wherever you relay the number downstream; it is a license requirement, not decoration.

This page is hand-maintained for readability. The live, always-current reference (with a Swagger UI you can call directly from the browser) is served at /api/docs, with the raw spec at /api/docs/openapi.json.

GET/api/index/:nodeId

Live index value for one geo node, derived from first-print ZHVI observations (up to 24 months of history).

Path Parameters

Name	Type	Description
nodeId*	string	Geo node id -- state:TX, county:48201 (5-digit FIPS), city:tx-austin, or zip:11215.

Response

json

{
  "success": true,
  "data": {
    "nodeId": "state:TX",
    "value": 312400,
    "yoy": 4.9,
    "asOfMonth": "2026-05",
    "series": [
      { "month": "2026-04", "value": 309800 },
      { "month": "2026-05", "value": 312400 }
    ],
    "source": "zhvi_first_print",
    "attribution": "Data from Zillow"
  }
}

bash

curl https://api.ziptoken.io/api/index/state:TX \
  -H "x-api-key: YOUR_KEY"   # optional

GET/api/index

Bulk-get index values for up to 50 node ids in one call. Unknown ids are reported separately rather than failing the whole request.

Query Parameters

Name	Type	Description
ids*	string	Comma-separated geo node ids, e.g. state:NY,zip:11215.

Response

json

{
  "success": true,
  "data": [
    {
      "nodeId": "state:NY",
      "value": 481200,
      "yoy": 3.1,
      "asOfMonth": "2026-05",
      "series": [ { "month": "2026-04", "value": 479600 }, { "month": "2026-05", "value": 481200 } ],
      "source": "zhvi_first_print",
      "attribution": "Data from Zillow"
    },
    {
      "nodeId": "zip:11215",
      "value": 968500,
      "yoy": 2.4,
      "asOfMonth": "2026-05",
      "series": [ { "month": "2026-04", "value": 964900 }, { "month": "2026-05", "value": 968500 } ],
      "source": "zhvi_first_print",
      "attribution": "Data from Zillow"
    }
  ],
  "unknownIds": ["county:99999"]
}

bash

curl "https://api.ziptoken.io/api/index?ids=state:NY,zip:11215,county:99999"

GET/api/markets

List markets with filters, paginated.

Query Parameters

Name	Type	Description
zip	string	5-digit zip code filter.
level	'state' \| 'county' \| 'city' \| 'neighborhood' \| 'zip'	Geo level filter.
state	string	Two-letter state filter (NY, CA, CO, TX, FL), matched against the geo hierarchy.
status	'ACTIVE' \| 'PAUSED' \| 'RESOLVED' \| 'CANCELLED' \| 'FINALIZED'	Market status filter.
page	number	Page number, default 1.
limit	number	Page size, default 20, max 100.

Response

json

{
  "success": true,
  "data": [
    {
      "id": "clx7f3k9p0000qzrm4h2b8v1n",
      "frontendId": "mkt-006",
      "onChainMarketId": "mkt-006",
      "conditionId": "0x9f2c1a...",
      "zipCode": "33101",
      "marketType": "BINARY",
      "status": "ACTIVE",
      "geoNodeId": "county:12086",
      "questionId": "county:12086",
      "outcomeCount": 2,
      "resolutionTimestamp": "2026-12-31T00:00:00.000Z",
      "description": "Miami-Dade County (FL) ZHVI level at or above $500,000 by Dec 2026",
      "threshold": "500000",
      "metricType": "median_sale_price",
      "createdAt": "2026-02-01T00:00:00.000Z",
      "updatedAt": "2026-07-10T00:00:00.000Z",
      "outcomes": [
        { "index": 0, "label": "YES", "positionId": "pos_mkt006_yes", "price": 0.34 },
        { "index": 1, "label": "NO", "positionId": "pos_mkt006_no", "price": 0.66 }
      ],
      "resolution": null
    }
  ],
  "pagination": { "page": 1, "limit": 3, "total": 11, "hasMore": true }
}

bash

curl "https://api.ziptoken.io/api/markets?level=county&state=FL&limit=3"

GET/api/markets/:id

Get a single market by database id or frontend id (e.g. mkt-002).

Path Parameters

Name	Type	Description
id*	string	Market id -- db UUID or frontend id like mkt-002.

Response

json

{
  "success": true,
  "data": {
    "id": "clx7f3k9p0002qzrm2c4d9v3n",
    "frontendId": "mkt-002",
    "onChainMarketId": "mkt-002",
    "conditionId": "0x4a7bd9f1e2c3...",
    "zipCode": "10001",
    "marketType": "BINARY",
    "status": "FINALIZED",
    "geoNodeId": "zip:10001",
    "questionId": "zip:10001",
    "outcomeCount": 2,
    "resolutionTimestamp": "2026-06-30T00:00:00.000Z",
    "description": "Will the ZHVI level for zip 10001 be at or above $1,300,000 in June 2026?",
    "threshold": "1300000",
    "metricType": "median_sale_price",
    "createdAt": "2026-01-10T00:00:00.000Z",
    "updatedAt": "2026-07-03T06:00:00.000Z",
    "outcomes": [
      { "index": 0, "label": "YES", "positionId": "pos_mkt002_yes", "price": 1 },
      { "index": 1, "label": "NO", "positionId": "pos_mkt002_no", "price": 0 }
    ],
    "resolution": {
      "outcome": "YES",
      "settledValue": 1341800,
      "resolvedAt": "2026-07-01T06:00:00.000Z",
      "disputeWindowEndsAt": "2026-07-03T06:00:00.000Z",
      "finalizedAt": "2026-07-03T06:00:00.000Z"
    }
  }
}

bash

curl https://api.ziptoken.io/api/markets/mkt-002

GET/api/markets/:id/resolution

Structured resolution status for a market: the settlement terms, the Zillow first-print observation it settled on, and dispute-window state. Fields stay null (not an error) until each stage happens.

Path Parameters

Name	Type	Description
id*	string	Market id -- db UUID or frontend id like mkt-002.

Response

json

{
  "success": true,
  "data": {
    "marketId": "mkt-002",
    "frontendId": "mkt-002",
    "status": "FINALIZED",
    "geoNodeId": "zip:10001",
    "metric": "zhvi_level",
    "comparator": "gte",
    "threshold": 1300000,
    "measurementMonth": "2026-06",
    "outcome": "YES",
    "settledValue": 1341800,
    "comparisonValue": null,
    "resolvedAt": "2026-07-01T06:00:00.000Z",
    "disputeWindowEndsAt": "2026-07-03T06:00:00.000Z",
    "finalizedAt": "2026-07-03T06:00:00.000Z",
    "observation": {
      "value": 1341800,
      "dataMonth": "2026-06",
      "releaseId": "zhvi-2026-06-first",
      "ingestedAt": "2026-07-01T04:12:00.000Z"
    }
  }
}

bash

curl https://api.ziptoken.io/api/markets/mkt-002/resolution

GET/api/geo/search

Search the geo hierarchy by zip, name, or alias. Ranked exact > prefix > substring, coarser levels first on ties.

Query Parameters

Name	Type	Description
q*	string	Search text.
limit	number	Max results, default 20, max 50.
level	'state' \| 'county' \| 'city' \| 'neighborhood' \| 'zip'	Restrict to one level.
state	'NY' \| 'CA' \| 'CO' \| 'TX' \| 'FL'	Restrict to one state.

Response

json

{
  "success": true,
  "data": [
    {
      "id": "city:tx-austin",
      "level": "city",
      "name": "Austin",
      "stateCode": "TX",
      "fips": null,
      "aliases": ["Austin, TX"],
      "parentIds": ["state:TX", "county:48453"],
      "housingUnits": 428500,
      "active": true,
      "childCount": 12
    }
  ]
}

bash

curl "https://api.ziptoken.io/api/geo/search?q=austin&level=city"

GET/api/geo/:id

Get one geo node plus its ancestor chain, ordered coarsest-first (state, county, city, ...).

Path Parameters

Name	Type	Description
id*	string	Geo node id, e.g. zip:11215.

Response

json

{
  "success": true,
  "data": {
    "id": "zip:11215",
    "level": "zip",
    "name": "11215",
    "stateCode": "NY",
    "fips": null,
    "aliases": [],
    "parentIds": ["state:NY", "county:36047", "city:ny-new-york-city", "nbhd:nyc-park-slope"],
    "housingUnits": 21400,
    "active": true,
    "childCount": 0,
    "ancestors": [
      { "id": "state:NY", "level": "state", "name": "New York" },
      { "id": "county:36047", "level": "county", "name": "Kings County" },
      { "id": "city:ny-new-york-city", "level": "city", "name": "New York City" },
      { "id": "nbhd:nyc-park-slope", "level": "neighborhood", "name": "Park Slope" }
    ]
  }
}

bash

curl https://api.ziptoken.io/api/geo/zip:11215

POST/api/dev/api-keys

Admin-only key issuance -- not self-serve yet. Guarded by an x-admin-secret header matching the ops-held API_KEY_ADMIN_SECRET; requests without it 401. Included for completeness -- most agent integrations will not call this directly, email api@ziptoken.io for a key instead.

Request Body

Name	Type	Description
label*	string	Human-readable label for the key.
scopes	string[]	Reserved for future fine-grained permissions.
rateLimit	number	Requests-per-window override.
expiresInDays	number	Key expiry in days.

Response

json

{
  "success": true,
  "data": {
    "key": "zt_pub_9f8e2a1c4b7d6e5f...",
    "id": "ak_3f9c2b1a",
    "label": "acme-agent",
    "scopes": null,
    "rateLimit": null,
    "expiresAt": null
  }
}

bash

curl -X POST https://api.ziptoken.io/api/dev/api-keys \
  -H "Content-Type: application/json" \
  -H "x-admin-secret: ADMIN_SECRET" \
  -d '{"label": "acme-agent"}'