Dead-Coin Desk API

REST API for the Dead-Coin Buyback Desk — price a delisted or abandoned token position from live DEX data, reserve the firm USDC bid, and track your orders. Quoting is public and unauthenticated; reserving and order history require a Bearer token.

Base URL

https://cymetica.com

Authentication

Only /quote is public. /reserve and /orders/mine need a Bearer token from the standard login endpoint:

curl -X POST https://cymetica.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "…"}'
# → {"access_token": "…"} — send as  Authorization: Bearer <token>

POST/api/v1/deadcoins/quote

Price a token position. Public, rate-limited. Omit amount_tokens for a per-token preview — previews cannot be reserved; re-quote with an amount to get a reservable quote.

Request body

Field	Type	Description
chain	string	auto (scans every chain) or one of ethereum, base, bsc, polygon, arbitrum, avalanche, optimism, solana
contract_address	string	Token contract address (0x…) or Solana mint
amount_tokens	string, optional	Position size in tokens. Omit for a preview quote

Response

Field	Description
tier	LIQUID (real bid), DUST (tax-loss disposal offer), or DECLINED
bid_usdc	The firm USDC bid for the position (LIQUID), or the nominal disposal bid (DUST)
discount_pct	Liquidity-scaled discount off fair value, 20–40% (LIQUID)
flat_fee_usdc	Flat disposal fee (DUST tier only)
price_usd / liquidity_usd / max_exit_usd / position_value_usd	The pricing evidence behind the bid
amount_tokens	The token count this bid is for. Send exactly this much — it may be less than you asked for (see partial_fill)
partial_fill	null normally. When the position exceeds the desk's per-order limit, an object with reason, requested_tokens, requested_position_value_usd and per_order_cap_usd: the bid covers amount_tokens at the same per-token price, and the remainder can be quoted again
decline_reason	Why a DECLINED quote was declined
quote_id	Pass to /reserve to accept
expires_at	Quote firm until this timestamp (~15 minutes)

curl -X POST https://cymetica.com/api/v1/deadcoins/quote \
  -H "Content-Type: application/json" \
  -d '{"chain": "auto",
       "contract_address": "0x1234…dead",
       "amount_tokens": "1500000"}'

POST/api/v1/deadcoins/reserve

Accept a quote — parks it as an order on the desk. Authenticated.

Field	Type	Description
quote_id	string (uuid)	A non-expired, non-preview, non-declined quote

Returns {order_id, status, settlement_open}. Errors: 404 unknown quote, 409 already reserved / declined / preview-only, 410 expired.

curl -X POST https://cymetica.com/api/v1/deadcoins/reserve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quote_id": "…"}'

GET/api/v1/deadcoins/orders/mine

Your 50 most recent desk orders, newest first. Authenticated.

curl https://cymetica.com/api/v1/deadcoins/orders/mine \
  -H "Authorization: Bearer $TOKEN"

Tiers

Tier	Meaning
LIQUID	Enough surviving DEX liquidity to exit — bid = fair value minus a 20–40% discount scaled by how much of the exitable depth the position consumes
DUST	No meaningful exit liquidity — tax-loss disposal offer: nominal bid plus a flat fee, with a receipt for your capital-loss claim
DECLINED	Blocklisted (regulatory) or unpriceable — decline_reason says why