knot-prototype-transactions（结原型交易）

Prototype with Transaction Data

Generate sample SKU-level transaction data from Knot's development API and use it immediately for prototyping — building UIs, exploring data shapes, or mocking up features. No SDK integration, no webhook setup, no production credentials. Just data.

API Reference

POST /development/accounts/link

Base URL: https://development.knotapi.com

Request body:

{
  "external_user_id": "string (required) — your unique identifier for the user",
  "merchant_id": "integer (required) — unique identifier for the merchant (use 19 for DoorDash)",
  "transactions": {
    "new": "boolean (required) — whether to generate new sample transactions",
    "updated": "boolean (optional, default false) — whether to also update some generated transactions. Requires new: true"
  }
}

Response (200):

{ "message": "Success" }

Errors: 401 with INVALID_API_KEYS means wrong credentials or using production keys against the development URL.

POST /transactions/sync

Base URL: https://development.knotapi.com

Request body:

{
  "merchant_id": "integer (required)",
  "external_user_id": "string (required)",
  "cursor": "string or null — null on first call, then pass next_cursor from previous response",
  "limit": "integer (optional, min 1, max 100, default 5)"
}

Response (200):

{
  "merchant": { "id": 19, "name": "DoorDash" },
  "transactions": [ ...array of transaction objects... ],
  "next_cursor": "string or null — null when no more pages remain",
  "limit": 100
}

Workflow

Step 1: Get Development API Keys

First, check whether the user already has a saved API key from a previous session. Look for a .env file in the working directory (or a parent) containing KNOT_DEV_API_KEY. If found, use it and skip to Step 2.

If no saved key exists, the user needs their development credentials from the Knot Dashboard. Walk them through it:

1. Go to https://dashboard.knotapi.com/developers/keys
2. Make sure the Development environment is selected (not Production)
3. Copy the Client ID (click the copy button)
4. Click View on the Secret to reveal it, then copy it

Ask the user to provide both values. Once they do, construct the API key:

API Key = base64("CLIENT_ID:SECRET")

Use base64 encoding (e.g., run echo -n "CLIENT_ID:SECRET" | base64 in the terminal) and set the resulting string as the Authorization: Basic <key> header for all subsequent API calls.

Save the key for future sessions: After constructing the base64-encoded API key, save it so the user doesn't need to retrieve their credentials again. Add it to a .env file in the working directory:

KNOT_DEV_API_KEY=<base64-encoded key>

If a .env file already exists, append the line. If .gitignore exists and doesn't already cover .env, add it. Mention to the user that this key is saved locally so they won't need to provide it again next time.

Important: These are development-only credentials. They only work against https://development.knotapi.com. Never use production credentials with this skill.

Step 2: Generate Sample Transactions

Ask the user which merchant(s) they want to generate transaction data for. Present this list:

• Walmart
• Amazon
• DoorDash
• Uber Eats
• Instacart
• Target
• Costco
• Gopuff
• Shop Pay

The user can pick one or multiple. For each selected merchant, call the development account link endpoint. No SDK or webhook setup is required — this endpoint simulates a full merchant account link and transaction generation server-side.

POST https://development.knotapi.com/development/accounts/link
Authorization: Basic <base64(client_id:secret)>
Content-Type: application/json

{
  "external_user_id": "prototype-user-1",
  "merchant_id": <merchant_id>,
  "transactions": {
    "new": true,
    "updated": false
  }
}

This generates ~205 sample transactions per merchant. The external_user_id can be any string — use something descriptive for the prototype session. Use the same external_user_id across merchants if the prototype involves a single user with multiple merchant accounts.

If running this multiple times, use a different external_user_id each time (e.g., prototype-user-2, prototype-user-3) to avoid conflicts with previously generated data.

Merchant ID reference:

Step 3: Retrieve Transactions

Poll the sync endpoint directly after the link call. No webhook is needed — just query for the data.

For each merchant the user selected, call POST /transactions/sync in a loop with a high limit to pull all generated transactions:

for each merchant_id:
  cursor = null

  loop:
    POST https://development.knotapi.com/transactions/sync
    Authorization: Basic <base64(client_id:secret)>
    Content-Type: application/json

    {
      "merchant_id": <merchant_id>,
      "external_user_id": "prototype-user-1",
      "cursor": cursor,
      "limit": 100
    }

    -> collect response.transactions (along with response.merchant for context)
    -> cursor = response.next_cursor
    -> break if cursor is null

With limit: 100 and ~205 sample transactions per merchant, each merchant takes about 3 pages. Collect all transactions into a single array (or group by merchant, depending on the prototype).

If the response returns 0 transactions, the data may not be ready yet. Retry the request. Development transaction generation typically completes within a few seconds.

Step 4: Use the Data

Once transactions are retrieved, ask the user how they want to use the data:

Option A: Prototype in this session

Keep the transaction data in memory and start building immediately. Use real field values from the retrieved data to make the prototype feel realistic.

Option B: Export to a Markdown file

Save the transaction data to a structured .md file that can be referenced later or shared with others. Write the file with this structure:

# Knot Transaction Data — Prototype

Generated: {date}
Merchant: {merchant_name} (ID: {merchant_id})
External User ID: {external_user_id}
Transaction Count: {count}

## Summary

- Total transactions: {count}
- Date range: {earliest_date} to {latest_date}
- Order statuses: {list of unique statuses with counts}
- Total spend: {sum of price.total values}

## Transactions

### {transaction.id}

- **Date:** {datetime}
- **Status:** {order_status}
- **Total:** {price.total} {price.currency}
- **Products:**
  - {product.name} (qty: {quantity}) — {product.price.total}
  - ...
- **Payment:** {payment_methods[0].type} ending {last_four}
- **Order URL:** {url}

...repeated for each transaction...

Save the file in the user's working directory (e.g., knot-transactions-prototype.md). This file can then be used as context for future prototyping sessions.

Transaction Object Reference

Each transaction returned by /transactions/sync has this shape:

Top-level fields

The merchant object ({id, name}) is in the sync response wrapper, not inside each transaction.

shipping

Nullable at the top level. Contains a single location field (also nullable).

shipping.location

shipping.location.address

products[]

products[].seller

payment_methods[]

price.adjustments[]

Each adjustment: type (enum: DISCOUNT, TAX, TIP, FEE, REFUND, UNRECOGNIZED), label (nullable string), amount (string — positive increases total, negative decreases).

Rules

• Development only. This skill uses https://development.knotapi.com exclusively. Never use production credentials or the production base URL.
• New user ID each run. Reusing the same external_user_id across multiple link calls can produce unexpected results. Increment or randomize the ID.
• Retry on empty results. If /transactions/sync returns 0 transactions, the data isn't ready yet. Retry the request.
• Paginate fully. Even in development, transactions come in pages. Loop until next_cursor is null.
• No webhooks. This prototyping flow skips webhook setup entirely. The sync endpoint returns data regardless of whether a webhook was received.
• Use the merchant ID table. Always look up the merchant ID from the reference table in Step 2. Do not guess or hardcode IDs.