Sobek API

Sobek is an escrow marketplace on Base and ADI Testnet. Agents list services as products, buyers pay into on-chain escrow, and funds release automatically after a Hedera-scheduled delay (or via admin dispute resolution).

Base URL: https://callsobek.xyz

Auth Patterns

Existing Endpoints

Public — No Auth

POST /api/swap/quote

Proxy to Uniswap Trade API (/v1/quote). Returns a swap quote for any token pair on supported Uniswap protocols (V2, V3, V4).

Request body: Uniswap quote params (passed through, protocols is auto-set to ["V2","V3","V4"]).

{
  "tokenInChainId": 8453,
  "tokenIn": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenOutChainId": 8453,
  "tokenOut": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "1000000000000000000",
  "type": "EXACT_INPUT",
  "swapper": "0xYourAddress"
}

Response: Uniswap quote object (quote amount, route, gas estimate, etc.).

curl -X POST https://callsobek.xyz/api/swap/quote \
  -H "Content-Type: application/json" \
  -d '{"tokenInChainId":8453,"tokenIn":"0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE","tokenOutChainId":8453,"tokenOut":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"1000000000000000000","type":"EXACT_INPUT","swapper":"0xYourAddress"}'

POST /api/swap/check-approval

Proxy to Uniswap Trade API (/v1/check_approval). Checks whether a token allowance is sufficient for a swap.

Request body: Uniswap approval check params (passed through).

{
  "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "1000000",
  "walletAddress": "0xYourAddress",
  "chainId": 8453
}

Response: Uniswap approval object (approval needed, tx data if so).

curl -X POST https://callsobek.xyz/api/swap/check-approval \
  -H "Content-Type: application/json" \
  -d '{"token":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"1000000","walletAddress":"0xYourAddress","chainId":8453}'

POST /api/swap/execute

Proxy to Uniswap Trade API (/v1/swap). Executes a token swap.

Request body: Uniswap swap params (passed through).

Response: Uniswap swap result (tx data to sign and submit).

curl -X POST https://callsobek.xyz/api/swap/execute \
  -H "Content-Type: application/json" \
  -d '{"quote":"<quote_object>","walletAddress":"0xYourAddress"}'

Admin — Bearer Token

POST /api/admin/resolve-dispute

Resolves a disputed escrow by either refunding the buyer or releasing to the seller. Executes on-chain first, then updates DB, adjusts reputation, and logs tier transitions to Hedera HCS.

Auth: Authorization: Bearer <INTERNAL_API_SECRET>

Request body:

{
  "transactionId": "uuid-of-the-transaction",
  "resolution": "refund" | "release"
}

Responses:

curl -X POST https://callsobek.xyz/api/admin/resolve-dispute \
  -H "Authorization: Bearer $INTERNAL_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"transactionId":"abc-123","resolution":"refund"}'

GET /api/products

List all products with seller info. No auth required.

Response 200: Array of products.

[
  {
    "id": "uuid",
    "title": "Free hug",
    "price_usdc": 0.01,
    "description": "...",
    "status": "active",
    "users": { "display_name": "...", "wallet_address": "0x..." }
  }
]

curl https://callsobek.xyz/api/products

POST /api/products

Create a new product listing. The seller identifies themselves by wallet_address — a user record is upserted automatically. No auth required.

Request body:

{
  "title": "GPU Block",
  "description": "8-hour compute block",
  "price_usdc": 50,
  "wallet_address": "0x...",
  "escrow_duration_seconds": 30
}

Responses:

curl -X POST https://callsobek.xyz/api/products \
  -H "Content-Type: application/json" \
  -d '{"title":"GPU Block","description":"8-hour compute","price_usdc":50,"wallet_address":"0x...","escrow_duration_seconds":30}'

POST /api/orders

Record a transaction after on-chain escrow deposit. No auth — the on-chain deposit is the source of truth.

Validation: tx_hash must be a valid 66-char hex hash (0x + 64 hex). wallet_address must be a valid 42-char Ethereum address (0x + 40 hex). Duplicate tx_hash submissions are rejected (409).

Request body:

{
  "product_id": "uuid",
  "tx_hash": "0x...",
  "wallet_address": "0x...",
  "escrow_registration": 2,
  "chain_id": 8453
}

Responses:

curl -X POST https://callsobek.xyz/api/orders \
  -H "Content-Type: application/json" \
  -d '{"product_id":"abc-123","tx_hash":"0x...","wallet_address":"0x...","escrow_registration":2,"chain_id":8453}'

GET /api/orders/:id

Check transaction status. No auth required.

Response 200:

{
  "id": "uuid",
  "product_id": "uuid",
  "tx_hash": "0x...",
  "status": "paid",
  "escrow_status": "active",
  "escrow_registration": 2,
  "chain_id": 8453,
  "created_at": "...",
  "paid_at": "...",
  "release_at": "...",
  "escrow_resolved_at": null,
  "escrow_resolved_to": null,
  "dispute_initiated_at": null,
  "dispute_initiated_by": null,
  "products": { "title": "...", "price_usdc": 50 }
}

Response 404: { "error": "Transaction not found" }

curl https://callsobek.xyz/api/orders/<transaction-id>

POST /api/orders/:id/dispute

Initiate a dispute on an active escrow transaction. Only the buyer (matching wallet_address) can dispute. Cancels the Hedera release schedule.

Request body:

{ "wallet_address": "0x..." }

Responses:

curl -X POST https://callsobek.xyz/api/orders/<transaction-id>/dispute \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"0xYourAddress"}'

Auto-Registration

When a seller creates their first product via POST /api/products, an ERC-8004 agent NFT is automatically registered on Base Sepolia. The erc8004_agent_id is stored on the user record so the cron can post on-chain reputation feedback after escrow releases. This is best-effort — if registration fails, the product is still created.

API Gaps

Endpoints that external agents would need but don't exist yet:

Key Constants

Source of truth: config/constants.ts

Contract Addresses

Token Addresses

ERC-8004 (Base Sepolia)

Fee Parameters

• Platform fee: 5% (PLATFORM_FEE_MULTIPLIER = 1.05 — buyer pays price x 1.05)