# Satoshi API AI Fee Advice

> Satoshi API AI Fee Advice is a paid API for AI agents from cdp.bitcoinsapi.com, paid per call via x402, $0.01/call, status down (last checked 2026-09-15).

Returns plain-language AI-generated Bitcoin fee recommendations with structured guidance on whether to send now or wait, target fee rate, and estimated savings.

## Facts

- Endpoint: GET https://cdp.bitcoinsapi.com/api/v1/ai/fees/advice
- Price: $0.01/call
- Payment: x402
- Status: down
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/cdp-bitcoinsapi-com-44a0c106
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_lSbggdBLG8OAal3mDxlLQ

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability cdp-bitcoinsapi-com-44a0c106
```

Example prompt: Should I send my 0.5 BTC payment right now or wait for lower fees — it's medium urgency, not something that needs to confirm in the next block?

## When to prefer this

Use this endpoint when you need a human-readable, AI-synthesized recommendation — not just raw fee numbers — especially for wallets, bots, or agents that need to communicate fee strategy in natural language to end users. Prefer this over raw fee estimator endpoints when you want a 'send vs wait' decision with confidence and savings context already computed. Ideal for DCA bots, payment processors, or wallet UIs that want opinionated guidance rather than raw sat/vB data.

## Known failure modes

- Upstream mempool or fee data unavailable — may return stale cached response or error
- Invalid urgency enum value returns 422 validation error
- Bitcoin node out of sync — meta.syncing flag set to true, advice may be unreliable
- Network timeout if Azure OpenAI backend is slow or unavailable
- x402 payment required if USDC payment header is missing or invalid

## How this service works

Satoshi API AI fee advice: plain-language Bitcoin fee recommendations for agents, wallets, and bots.

## Output

A JSON object containing a human-readable advice string explaining whether to send or wait, the recommended fee in sat/vB, the current fee environment label (e.g. 'rock-bottom'), confidence level, estimated savings percentage versus sending immediately, and the urgency echo. Also includes structured fields: wait (bool), action, confidence, fee_environment, recommended_fee_sat_vb, and raw fee data for next-block/6-block/1-day windows.

## Example request

```json
{
 "input": {
  "queryParams": {
   "context": "payment",
   "urgency": "medium",
   "amount_btc": "0.5"
  }
 }
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "input": {
  "type": "http",
  "method": "GET",
  "resource": "https://cdp.bitcoinsapi.com/api/v1/ai/fees/advice",
  "queryParams": {
   "context": {
    "type": "string",
    "required": false,
    "description": "Transaction context: DCA, consolidation, payment, etc."
   },
   "urgency": {
    "enum": [
     "low",
     "medium",
     "high"
    ],
    "type": "string",
    "default": "medium",
    "required": false,
    "description": "Transaction urgency"
   },
   "amount_btc": {
    "type": "string",
    "required": false,
    "description": "Transaction amount in BTC (optional context)"
   }
  }
 },
 "output": {
  "type": "json",
  "schema": {
   "type": "object",
   "required": [
    "advice"
   ],
   "properties": {
    "advice": {
     "type": "string"
    },
    "urgency": {
     "type": "string"
    },
    "provider": {
     "type": "string"
    },
    "structured": {
     "type": "object"
    }
   }
  },
  "example": {
   "advice": "Wait if the transaction is not urgent; target 12 sat/vB for a lower-cost confirmation.",
   "urgency": "normal",
   "provider": "satoshi-api",
   "structured": {
    "recommendation": "wait",
    "targetFeeSatVb": 12,
    "estimatedSavingsPct": 46.8
   }
  },
  "mimeType": "application/json"
 },
 "properties": {
  "input": {
   "type": "object",
   "properties": {
    "queryParams": {
     "context": {
      "type": "string",
      "required": false,
      "description": "Transaction context: DCA, consolidation, payment, etc."
     },
     "urgency": {
      "enum": [
       "low",
       "medium",
       "high"
      ],
      "type": "string",
      "default": "medium",
      "required": false,
      "description": "Transaction urgency"
     },
     "amount_btc": {
      "type": "string",
      "required": false,
      "description": "Transaction amount in BTC (optional context)"
     }
    }
   }
  },
  "output": {
   "type": "object",
   "required": [
    "type",
    "mimeType",
    "example"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "schema": {
     "type": "object"
    },
    "example": {
     "type": "object"
    },
    "mimeType": {
     "type": "string"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "required": [
  "data",
  "meta"
 ],
 "properties": {
  "data": {
   "type": "object",
   "required": [
    "advice",
    "context",
    "urgency",
    "fee_data",
    "provider",
    "structured"
   ],
   "properties": {
    "advice": {
     "type": "string"
    },
    "context": {
     "type": "string"
    },
    "urgency": {
     "type": "string"
    },
    "fee_data": {
     "type": "object",
     "required": [
      "1_day_sat_vb",
      "6_blocks_sat_vb",
      "next_block_sat_vb"
     ],
     "properties": {
      "1_day_sat_vb": {
       "type": "number"
      },
      "6_blocks_sat_vb": {
       "type": "number"
      },
      "next_block_sat_vb": {
       "type": "number"
      }
     }
    },
    "provider": {
     "type": "string"
    },
    "structured": {
     "type": "object",
     "required": [
      "wait",
      "action",
      "confidence",
      "fee_environment",
      "estimated_savings_pct",
      "recommended_fee_sat_vb"
     ],
     "properties": {
      "wait": {
       "type": "boolean"
      },
      "action": {
       "type": "string"
      },
      "confidence": {
       "type": "string"
      },
      "fee_environment": {
       "type": "string"
      },
      "estimated_savings_pct": {
       "type": "number"
      },
      "recommended_fee_sat_vb": {
       "type": "number"
      }
     }
    }
   }
  },
  "meta": {
   "type": "object",
   "required": [
    "chain",
    "cached",
    "syncing",
    "timestamp",
    "max_blocks",
    "request_id",
    "node_height",
    "cache_age_seconds"
   ],
   "properties": {
    "chain": {
     "type": "string"
    },
    "cached": {
     "type": "boolean"
    },
    "syncing": {
     "type": "boolean"
    },
    "timestamp": {
     "type": "string"
    },
    "max_blocks": {
     "type": "null"
    },
    "request_id": {
     "type": "null"
    },
    "node_height": {
     "type": "number"
    },
    "cache_age_seconds": {
     "type": "number"
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/cdp-bitcoinsapi-com-44a0c106/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from cdp.bitcoinsapi.com](https://www.zero.xyz/host/cdp.bitcoinsapi.com/llms.txt)