marketplace

List the markets this marketplace facilitates (asset, chain, currencies, fee).

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Active listings/auctions for a market. Each row carries the ask and the position's underlying contents priced at current market (published formula: /docs#data-sources), plus discountPct (the difference between them). Sorted by discount percentage, descending.

{
  "type": "object",
  "properties": {
    "marketId": {
      "type": "string",
      "description": "market id, e.g. 'vehydx'"
    },
    "kind": {
      "type": "string",
      "enum": [
        "listing",
        "dutch_auction",
        "offer"
      ]
    },
    "minDiscountPct": {
      "description": "only return orders at >= this discount %. IGNORED on markets whose asset has no priced underlying, where there is nothing to compare the ask against — the response says so in `note` rather than returning an empty market.",
      "type": "number"
    },
    "nameContains": {
      "description": "case-insensitive substring match on the listing's label (the name on name markets, e.g. 'alice'; 'veAERO #123' elsewhere)",
      "type": "string",
      "maxLength": 64
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "marketId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Full detail for one order including a FRESH live-contents snapshot (principal, claimable rewards, voting/earning power, as_of_block).

{
  "type": "object",
  "properties": {
    "orderHash": {
      "type": "string"
    }
  },
  "required": [
    "orderHash"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Recently settled sales for a market. `amount` is the EXACT settled total (incl. fee) from the on-chain fill where the indexer recorded it, with `settledAt` the block time and `exact: true`; otherwise it falls back to the listed ask with `exact: false` (a decayed Dutch auction settles BELOW its listed amount, so treat inexact rows as an upper bound).

{
  "type": "object",
  "properties": {
    "marketId": {
      "type": "string"
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "marketId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Prepare the non-custodial transaction package to BUY a listing (or accept an offer): ordered approvals + Seaport fulfillOrder calldata + a fresh contents snapshot. prepared.summary quotes the CURRENT price (Dutch auctions interpolate, asOf says when); the approval grants approveBaseUnits — slightly above the quote on a decaying order, never above maxTotalBaseUnits — and Seaport charges the exact interpolated amount at fill. On auctions, prepared.cleanup is an optional post-settlement tx that zeroes the residual allowance. The agent's own wallet signs and submits — this never signs or holds keys.

{
  "type": "object",
  "properties": {
    "orderHash": {
      "type": "string"
    }
  },
  "required": [
    "orderHash"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Prepare a BID/offer on a position: returns the Seaport order to sign (EIP-712), the currency approval needed, and how to submit it. The agent reads its Seaport counter, signs, and POSTs the signed order — settlement stays on Seaport.

{
  "type": "object",
  "properties": {
    "marketId": {
      "type": "string"
    },
    "tokenId": {
      "description": "required for token markets (e.g. vehydx)",
      "type": "string"
    },
    "name": {
      "description": "name markets only, e.g. 'alice' or 'alice.base.eth' — tokenId is derived",
      "type": "string"
    },
    "currencySymbol": {
      "type": "string",
      "enum": [
        "USDC",
        "WETH",
        "HYDX",
        "AERO",
        "USDT",
        "THE",
        "KITTEN",
        "NEST",
        "USDG",
        "UP"
      ],
      "description": "one of the market's settlementCurrencies (see list_micro_markets)"
    },
    "offerAmount": {
      "type": "string",
      "pattern": "^\\d+(\\.\\d+)?$",
      "description": "human amount the seller nets, e.g. '750' — must be positive"
    },
    "buyer": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "0x address that will sign and fund the offer"
    },
    "durationDays": {
      "type": "number",
      "minimum": 1,
      "maximum": 90
    }
  },
  "required": [
    "marketId",
    "currencySymbol",
    "offerAmount",
    "buyer"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Prepare a SELL listing or Dutch auction. Verifies the seller OWNS the position and it's transferable (not voted/attached), builds the Seaport order with the Interface fee injected by the server, and returns the one-time NFT approval + EIP-712 typed data to sign. Never signs or holds keys.

{
  "type": "object",
  "properties": {
    "marketId": {
      "type": "string"
    },
    "tokenId": {
      "description": "required for token markets (e.g. vehydx)",
      "type": "string"
    },
    "name": {
      "description": "name markets only, e.g. 'alice' or 'alice.base.eth' — tokenId is derived",
      "type": "string"
    },
    "kind": {
      "type": "string",
      "enum": [
        "listing",
        "dutch_auction"
      ]
    },
    "currencySymbol": {
      "type": "string",
      "enum": [
        "USDC",
        "WETH",
        "HYDX",
        "AERO",
        "USDT",
        "THE",
        "KITTEN",
        "NEST",
        "USDG",
        "UP"
      ],
      "description": "one of the market's settlementCurrencies (see list_micro_markets)"
    },
    "seller": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    },
    "ask": {
      "description": "listing: price the seller nets — must be positive",
      "type": "string",
      "pattern": "^\\d+(\\.\\d+)?$"
    },
    "startAsk": {
      "description": "dutch_auction: starting (high) price",
      "type": "string",
      "pattern": "^\\d+(\\.\\d+)?$"
    },
    "endAsk": {
      "description": "dutch_auction: floor price (must be below the start)",
      "type": "string",
      "pattern": "^\\d+(\\.\\d+)?$"
    },
    "durationDays": {
      "type": "number",
      "minimum": 1,
      "maximum": 90
    }
  },
  "required": [
    "marketId",
    "kind",
    "currencySymbol",
    "seller"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Prepare the on-chain Seaport cancel transaction for an active order. Only the order's offerer can execute it (Seaport enforces msg.sender == offerer), so the calldata is safe to return. After it confirms, POST { txHash } to the confirm endpoint to update the book.

{
  "type": "object",
  "properties": {
    "orderHash": {
      "type": "string"
    }
  },
  "required": [
    "orderHash"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List orders created by an address (its listings, auctions, offers). Status is reconciled by the background worker — treat as advisory until checked at fill.

{
  "type": "object",
  "properties": {
    "offerer": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "filled",
        "cancelled",
        "expired"
      ]
    }
  },
  "required": [
    "offerer"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List the positions an address owns in a market, with listability (voted/attached positions can't transfer).

{
  "type": "object",
  "properties": {
    "marketId": {
      "type": "string"
    },
    "owner": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    }
  },
  "required": [
    "marketId",
    "owner"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Subscribe a wallet to push notifications (order_filled / offer_received / saved_search) via an HMAC-signed webhook — the agent-native alternative to polling. Two-step: call WITHOUT `signature` to get the exact message to sign (EIP-191 personal_sign), then call again WITH the signature. `chainId` is signed over and the signature is verified on THAT chain, so pass the chain the wallet actually signs on (smart-wallet signatures do not validate cross-chain). Each signed message is SINGLE-USE: resending the same body returns 409 replayed_signature — retry with a fresh timestamp and a new signature. The response includes the webhook HMAC secret ONCE (verify x-market0x-signature = hex(HMAC-SHA256(rawBody, secret))).

{
  "type": "object",
  "properties": {
    "wallet": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    },
    "chainId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "chain the wallet signs on; it is part of the signed message"
    },
    "channel": {
      "type": "string",
      "enum": [
        "webhook",
        "inapp"
      ]
    },
    "webhookUrl": {
      "description": "https URL; required for the webhook channel",
      "type": "string",
      "format": "uri"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "order_filled",
          "offer_received",
          "saved_search"
        ]
      }
    },
    "savedSearch": {
      "type": "object",
      "properties": {
        "marketId": {
          "type": "string"
        },
        "kind": {
          "type": "string",
          "enum": [
            "listing",
            "dutch_auction"
          ]
        },
        "nameContains": {
          "description": "name markets: substring match on listed names",
          "type": "string",
          "maxLength": 64
        }
      },
      "required": [
        "marketId"
      ]
    },
    "timestamp": {
      "type": "number",
      "description": "unix seconds; must be within 10 minutes of now"
    },
    "signature": {
      "description": "EIP-191 signature of the canonical message; omit to receive the message to sign",
      "type": "string"
    }
  },
  "required": [
    "wallet",
    "chainId",
    "channel",
    "events",
    "timestamp"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List a wallet's notification subscriptions (webhook URLs redacted to origin).

{
  "type": "object",
  "properties": {
    "wallet": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    }
  },
  "required": [
    "wallet"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Delete a notification subscription. Two-step like subscribe_notifications: call without `signature` to get the message to sign. `chainId` is signed over and verified on that chain. Signed messages are single-use.

{
  "type": "object",
  "properties": {
    "wallet": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    },
    "chainId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "chain the wallet signs on; it is part of the signed message"
    },
    "subscriptionId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "timestamp": {
      "type": "number"
    },
    "signature": {
      "type": "string"
    }
  },
  "required": [
    "wallet",
    "chainId",
    "subscriptionId",
    "timestamp"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}