BTC DCA Engine

Assets this endpoint can simulate, with the date each series starts and ends. Call before composing a plan so start dates fall inside coverage.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The vintage of the loaded price data and how often it refreshes.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Simulate one dollar-cost-averaging plan against real historical closes. Returns totals, end-of-year checkpoints and a share_url that opens the same run in the app.

{
  "type": "object",
  "properties": {
    "asset": {
      "type": "string",
      "description": "Asset key from list_assets, e.g. \"btc_daily\", \"Ethereum\", \"S&P 500\"."
    },
    "type": {
      "description": "\"dca\" repeats on the schedule; \"lump-sum\" buys once at the start. Default \"dca\".",
      "type": "string",
      "enum": [
        "dca",
        "lump-sum"
      ]
    },
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "USD per contribution, or the single amount for lump-sum."
    },
    "frequency": {
      "description": "Contribution cadence. Default \"monthly\". Quarterly is the coarsest offered: wider gaps behave like a few lump sums (see the knowledge base, \"The gap between buys\").",
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly",
        "quarterly"
      ]
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First scheduled contribution."
    },
    "end_date": {
      "description": "Window end. Defaults to the last loaded close, never a relative \"today\".",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "wait_periods": {
      "description": "Save this many scheduled contributions as cash before the first purchase.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "last_buy_date": {
      "description": "Stop buying here and hold to end_date.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "as_of": {
      "description": "Pin the answer to this data vintage so the share link keeps returning the same number.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "settings": {
      "description": "Chart overlays carried into share_url, and the figures they add to each summary. Flags marked \"Pro only\" need a signed-in Pro account or a Pro API key; without one, the call returns an error naming the setting.",
      "type": "object",
      "properties": {
        "fng": {
          "description": "Draw the Fear & Greed overlay on the shared chart.",
          "type": "boolean"
        },
        "log": {
          "description": "Log scale on the shared chart.",
          "type": "boolean"
        },
        "lump": {
          "description": "Pro only. Lump-sum benchmark: the same total bought at once on day one. Adds lump_sum_equivalent_final_value to the summary and the overlay to share_url.",
          "type": "boolean"
        },
        "cpi": {
          "description": "Pro only. Inflation arm: what the contributed cash is worth after CPI-U. Adds cash_after_cpi to the summary and the overlay to share_url.",
          "type": "boolean"
        },
        "mayer": {
          "description": "Pro only. Mayer Multiple overlay on the shared chart.",
          "type": "boolean"
        },
        "risk": {
          "description": "Pro only. Adds annualized sharpe and sortino to the summary.",
          "type": "boolean"
        },
        "smart": {
          "description": "Pro only. Buy rule: a signal read on each purchase date, two thresholds, and a multiplier for each of the three bands they make. `true` is the Mayer default (0.8/2.4 — buy as usual, skip above 2.4); an object sets its own. Adds `rule` and `rule_finding` (cost per unit against flat purchases from fixed starts) to the summary and the rule to share_url.",
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "object",
              "properties": {
                "signal": {
                  "description": "Which reading decides each purchase. mayer (default): price vs its 200-day average, Bitcoin, Ethereum, Solana and XRP. fng: the alternative.me Fear & Greed index (0-100), the same four assets. dd: percent below the running high close, any market asset (not bonds or index levels).",
                  "type": "string",
                  "enum": [
                    "mayer",
                    "fng",
                    "dd"
                  ]
                },
                "low": {
                  "description": "Lower threshold, from the signal's own list — mayer 0.5/0.6/0.7/0.8/0.9/1/1.2/1.5/2/2.4/3; fng 10/20/25/30/40/45/55/60/70/75/80/90; dd 10/20/30/40/50/60/70/80. Defaults mayer 0.8, fng 25, dd 20.",
                  "type": "number"
                },
                "high": {
                  "description": "Upper threshold, from the same list and above low. Defaults mayer 2.4, fng 75, dd 50.",
                  "type": "number"
                },
                "below": {
                  "description": "Multiplier on the scheduled amount when the reading is under low: one of 0, 0.25, 0.5, 1, 2, 3, 4, 6. 0 skips the purchase (that money is not invested).",
                  "type": "number"
                },
                "between": {
                  "description": "Multiplier when the reading is between the thresholds, same list. Default 1.",
                  "type": "number"
                },
                "above": {
                  "description": "Multiplier when the reading is over high, same list. Defaults: mayer 0 and fng 0 (skip the euphoric top), dd 2 (double in a deep drawdown).",
                  "type": "number"
                },
                "bank": {
                  "description": "Hold and deploy: the cash a band below 1× withholds is kept and spent on the next purchase the rule does not scale down, and counts as invested from the day it was scheduled. With no band above 1× the rule then invests the same total as flat purchases, so final value is comparable too. Any pile still standing at the end is reported as cash_held. Default false.",
                  "type": "boolean"
                }
              },
              "additionalProperties": false
            }
          ]
        }
      },
      "additionalProperties": false
    },
    "include": {
      "type": "object",
      "properties": {
        "ledger": {
          "description": "Per-purchase rows: \"none\" (default), \"head\" (first 20), \"all\" (capped at 200).",
          "type": "string",
          "enum": [
            "none",
            "head",
            "all"
          ]
        },
        "checkpoints": {
          "description": "End-of-year value points. Default \"yearly\".",
          "type": "string",
          "enum": [
            "yearly",
            "none"
          ]
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "asset",
    "amount",
    "start_date"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Run up to 5 plans over the same data and rank them by final value (2 without a signed-in Pro account or a Pro API key). Use to compare assets, cadences or start dates side by side. One share_url opens them all together.

{
  "type": "object",
  "properties": {
    "plans": {
      "minItems": 1,
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "asset": {
            "type": "string",
            "description": "Asset key from list_assets, e.g. \"btc_daily\", \"Ethereum\", \"S&P 500\"."
          },
          "type": {
            "description": "\"dca\" repeats on the schedule; \"lump-sum\" buys once at the start. Default \"dca\".",
            "type": "string",
            "enum": [
              "dca",
              "lump-sum"
            ]
          },
          "amount": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "USD per contribution, or the single amount for lump-sum."
          },
          "frequency": {
            "description": "Contribution cadence. Default \"monthly\". Quarterly is the coarsest offered: wider gaps behave like a few lump sums (see the knowledge base, \"The gap between buys\").",
            "type": "string",
            "enum": [
              "daily",
              "weekly",
              "monthly",
              "quarterly"
            ]
          },
          "start_date": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "First scheduled contribution."
          },
          "end_date": {
            "description": "Window end. Defaults to the last loaded close, never a relative \"today\".",
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "wait_periods": {
            "description": "Save this many scheduled contributions as cash before the first purchase.",
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "last_buy_date": {
            "description": "Stop buying here and hold to end_date.",
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          }
        },
        "required": [
          "asset",
          "amount",
          "start_date"
        ],
        "additionalProperties": false
      },
      "description": "The plans to compare: up to 2 anonymously or on a Free-account key, up to 5 with a signed-in Pro account or a Pro API key."
    },
    "as_of": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "settings": {
      "description": "Chart overlays carried into share_url, and the figures they add to each summary. Flags marked \"Pro only\" need a signed-in Pro account or a Pro API key; without one, the call returns an error naming the setting.",
      "type": "object",
      "properties": {
        "fng": {
          "description": "Draw the Fear & Greed overlay on the shared chart.",
          "type": "boolean"
        },
        "log": {
          "description": "Log scale on the shared chart.",
          "type": "boolean"
        },
        "lump": {
          "description": "Pro only. Lump-sum benchmark: the same total bought at once on day one. Adds lump_sum_equivalent_final_value to the summary and the overlay to share_url.",
          "type": "boolean"
        },
        "cpi": {
          "description": "Pro only. Inflation arm: what the contributed cash is worth after CPI-U. Adds cash_after_cpi to the summary and the overlay to share_url.",
          "type": "boolean"
        },
        "mayer": {
          "description": "Pro only. Mayer Multiple overlay on the shared chart.",
          "type": "boolean"
        },
        "risk": {
          "description": "Pro only. Adds annualized sharpe and sortino to the summary.",
          "type": "boolean"
        },
        "smart": {
          "description": "Pro only. Buy rule: a signal read on each purchase date, two thresholds, and a multiplier for each of the three bands they make. `true` is the Mayer default (0.8/2.4 — buy as usual, skip above 2.4); an object sets its own. Adds `rule` and `rule_finding` (cost per unit against flat purchases from fixed starts) to the summary and the rule to share_url.",
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "object",
              "properties": {
                "signal": {
                  "description": "Which reading decides each purchase. mayer (default): price vs its 200-day average, Bitcoin, Ethereum, Solana and XRP. fng: the alternative.me Fear & Greed index (0-100), the same four assets. dd: percent below the running high close, any market asset (not bonds or index levels).",
                  "type": "string",
                  "enum": [
                    "mayer",
                    "fng",
                    "dd"
                  ]
                },
                "low": {
                  "description": "Lower threshold, from the signal's own list — mayer 0.5/0.6/0.7/0.8/0.9/1/1.2/1.5/2/2.4/3; fng 10/20/25/30/40/45/55/60/70/75/80/90; dd 10/20/30/40/50/60/70/80. Defaults mayer 0.8, fng 25, dd 20.",
                  "type": "number"
                },
                "high": {
                  "description": "Upper threshold, from the same list and above low. Defaults mayer 2.4, fng 75, dd 50.",
                  "type": "number"
                },
                "below": {
                  "description": "Multiplier on the scheduled amount when the reading is under low: one of 0, 0.25, 0.5, 1, 2, 3, 4, 6. 0 skips the purchase (that money is not invested).",
                  "type": "number"
                },
                "between": {
                  "description": "Multiplier when the reading is between the thresholds, same list. Default 1.",
                  "type": "number"
                },
                "above": {
                  "description": "Multiplier when the reading is over high, same list. Defaults: mayer 0 and fng 0 (skip the euphoric top), dd 2 (double in a deep drawdown).",
                  "type": "number"
                },
                "bank": {
                  "description": "Hold and deploy: the cash a band below 1× withholds is kept and spent on the next purchase the rule does not scale down, and counts as invested from the day it was scheduled. With no band above 1× the rule then invests the same total as flat purchases, so final value is comparable too. Any pile still standing at the end is reported as cash_held. Default false.",
                  "type": "boolean"
                }
              },
              "additionalProperties": false
            }
          ]
        }
      },
      "additionalProperties": false
    },
    "include": {
      "type": "object",
      "properties": {
        "ledger": {
          "description": "Per-purchase rows: \"none\" (default), \"head\" (first 20), \"all\" (capped at 200).",
          "type": "string",
          "enum": [
            "none",
            "head",
            "all"
          ]
        },
        "checkpoints": {
          "description": "End-of-year value points. Default \"yearly\".",
          "type": "string",
          "enum": [
            "yearly",
            "none"
          ]
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "plans"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}