mortgagefi-helper/docs/Architecture/API Reference.md

title, tags, type, status, updated

title	tags	type	status	updated
API Reference	mortgagefi api reference	reference	stable	2026-06-14

API Reference

nftcache API

Base URL: http://localhost:8090 (or /nftcache when proxied)

Authentication

[!info] If NFTCACHE_API_KEY is configured, include it in the X-API-Key header for all requests.

---

GET /nfts

Returns token IDs owned by a specific wallet for a given NFT contract.

Query Parameters:

Parameter	Type	Required	Description
network	string	Yes	Network key: eth, arb, base
nft_contract	string	Yes	Contract address or config slug (e.g., cbbtc)
user_wallet	string	Yes	Owner wallet address

Response (200):

{
  "token_ids": ["1", "5", "42"],
  "source": "cache"
}

Sources:

• cache — Returned from BadgerDB cache
• refreshed — Fetched live from RPC and cached

Errors:

• 400 — Missing required parameters
• 401 — Invalid or missing API key
• 502 — RPC fetch error (rate limit, node unavailable)

---

POST /nfts/refresh

Force a full refresh of the contract ownership cache.

Query Parameters:

Parameter	Type	Required	Description
network	string	Yes	Network key
nft_contract	string	Yes	Contract address or slug

Response:

• 204 No Content — Success
• 401 — Unauthorized
• 502 — RPC error

---

POST /nfts/invalidate

Delete a contract's cache entry.

Query Parameters:

Parameter	Type	Required	Description
network	string	Yes	Network key
nft_contract	string	Yes	Contract address

Response:

• 204 No Content — Success
• 401 — Unauthorized

---

Schedy API

Base URL: http://localhost:8080 (or /schedy when proxied)

Authentication

[!info] If SCHEDY_API_KEY is configured, include it in the X-API-Key header for all requests.

---

POST /tasks

Create a new scheduled task.

Request Body:

{
  "url": "https://ntfy.sh/mytopic",
  "headers": {
    "Content-Type": "text/plain",
    "X-Email": "user@example.com"
  },
  "payload": "Your position is approaching liquidation",
  "execute_at": "2026-05-10T12:00:00Z",
  "retries": 3,
  "retry_interval": 2000
}

Fields:

Field	Type	Required	Default	Description
url	string	Yes	—	Webhook target URL
headers	object	No	{}	HTTP headers to send
payload	any	No	null	Request body (string or JSON)
execute_at	string	Yes	—	ISO 8601 / RFC3339 timestamp
retries	int	No	0	Max retry attempts on failure
retry_interval	int	No	2000	Milliseconds between retries

Response (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://ntfy.sh/mytopic",
  "execute_at": "2026-05-10T12:00:00Z",
  "headers": { "Content-Type": "text/plain" },
  "payload": "Your position is approaching liquidation",
  "retries": 3,
  "retry_interval": 2000
}

Errors:

• 400 — Invalid body or timestamp
• 400 — Timestamp is in the past
• 401 — Missing API key
• 403 — Invalid API key

---

GET /tasks

List all scheduled tasks.

Response (200):

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://ntfy.sh/mytopic",
    "execute_at": "2026-05-10T12:00:00Z",
    "headers": {},
    "payload": "...",
    "retries": 3,
    "retry_interval": 2000
  }
]

---

DELETE /tasks/{id}

Delete a scheduled task by ID.

Response:

• 204 No Content — Success
• 404 — Task not found
• 401 / 403 — Auth error

---

ntfy API (Proxied)

Base URL: http://localhost/ntfy (when behind nginx)

POST /{topic}

Publish a message to a topic.

Request Headers:

Header	Description
Content-Type: text/plain	Message body is plain text
X-Email: user@example.com	Forward message via email
X-Priority: 5	Message priority (1-5)

Example:

curl -X POST -H 'Content-Type: text/plain' -H 'X-Email: user@example.com' \
  http://localhost/ntfy/mytopic \
  -d 'Your position is approaching liquidation'

Response:

• 200 OK — Message published

Web UI

Access http://localhost/ntfy/ to use the ntfy web interface for subscribing to topics.

Related

• Home
• Architecture
• Deployment