---
name: enchant-agents
version: 0.4.0
description: Install Enchant for Agents to check funding state, discover services, inspect endpoint schemas, generate structured provider plans, execute routed provider calls, and poll async jobs.
---

# Enchant for Agents

Enchant for Agents is the agent-native version of Enchant.

Use it when a task may need one of Enchant's paid services across research, scraping, browser automation, image generation, video, voice, code execution, social data, travel, messaging, storage, and more.

## Required Configuration

Before using Enchant for Agents, the user must provide:

1. An Enchant base URL
2. An Enchant account
3. An Enchant API key if the host client is using manual bearer auth

Credits are required only for paid runs. They can be added during hosted setup or later through the agent funding routes.

If the user does not want to fund Enchant first, the agent can instead prepare a Base x402 or Tempo MPP request for direct local wallet execution.

If the agent supports MCP, it can also connect directly to:

- `{ENCHANT_BASE_URL}/mcp`

For manual bearer installs, store them as:

- `ENCHANT_BASE_URL`
- `ENCHANT_API_KEY`

For every request, send:

```text
Authorization: Bearer <ENCHANT_API_KEY>
Content-Type: application/json
```

## Current Workflow

For now, always use this flow:

1. `account` or `fund/options` when auth state, credits, or shortfall guidance matter
2. `discover` relevant services
3. `inspect` the chosen service
4. `plan` the request
5. `direct/prepare` when the user wants direct Base or Tempo wallet settlement from the agent host
6. `run` when the user wants Enchant-funded execution
7. `run/status` when the provider responds asynchronously

Do not invent endpoint paths or request schemas. Always inspect or plan first.

## Endpoints

### Install

`GET {ENCHANT_BASE_URL}/api/agent/v1/install`

Use this public manifest to learn setup links, auth expectations, and available routes before the first authenticated call.

### LLM hints

`GET {ENCHANT_BASE_URL}/llms.txt`

Use this when the host client or agent framework supports `llms.txt` discovery.

### Agent instructions

`GET {ENCHANT_BASE_URL}/agents/AGENTS.md`

Use this when the host agent supports selection hints or repo-style AGENTS instructions.

### MCP

`{ENCHANT_BASE_URL}/mcp`

Use this Streamable HTTP MCP endpoint when the host agent supports remote MCP servers.

### Account

`GET {ENCHANT_BASE_URL}/api/agent/v1/account`

Use this to inspect the authenticated account, current credits, install links, and saved payment preference.

### Funding Options

`GET {ENCHANT_BASE_URL}/api/agent/v1/fund/options`

Use this to inspect shortfall guidance, recommended credit packs, and the available card or wallet funding paths on Base or Tempo.

### Start Hosted Checkout

`POST {ENCHANT_BASE_URL}/api/agent/v1/fund/checkout`

Use this to create a hosted Stripe Checkout session for Enchant credits.

### Poll Hosted Checkout

`GET {ENCHANT_BASE_URL}/api/agent/v1/fund/status`

Use this to poll a hosted checkout session until credits arrive on the account.

### Prepare Wallet Top-Up

`POST {ENCHANT_BASE_URL}/api/agent/v1/fund/wallet/prepare`

Use this to create a wallet top-up intent and signing message on Base or Tempo. Pass `chain: "base"` or `chain: "tempo"` in the request body when you need a specific rail.

### Confirm Wallet Top-Up

`POST {ENCHANT_BASE_URL}/api/agent/v1/fund/wallet/confirm`

Use this to confirm the Base or Tempo wallet transfer and credit the Enchant account.

### Prepare Direct Wallet Execution

`POST {ENCHANT_BASE_URL}/api/agent/v1/direct/prepare`

Use this to turn a planned request into a payment-ready Base x402 or Tempo MPP call for local execution with `ENCHANT_EVM_PRIVATE_KEY` on the agent host.

### Discover

`POST {ENCHANT_BASE_URL}/api/agent/v1/discover`

Body example:

```json
{
  "query": "recent tweets about AI agents",
  "limit": 5
}
```

### Inspect

`POST {ENCHANT_BASE_URL}/api/agent/v1/inspect`

Body example:

```json
{
  "service": "stablesocial"
}
```

### Plan

`POST {ENCHANT_BASE_URL}/api/agent/v1/plan`

Body example:

```json
{
  "prompt": "Find recent tweets about AI agents and summarize the themes"
}
```

### Run

`POST {ENCHANT_BASE_URL}/api/agent/v1/run`

Body example:

```json
{
  "prompt": "Find recent tweets about AI agents and summarize the themes"
}
```

### Run Status

`POST {ENCHANT_BASE_URL}/api/agent/v1/run/status`

Body example:

```json
{
  "statusToken": "<STATUS_TOKEN>"
}
```

## Behavior Rules

- Check `install` early if you need setup links or you are being installed into a new agent platform.
- Prefer MCP over raw HTTP when the host agent supports remote MCP servers.
- Check `account` early when cost-awareness or auth state matters.
- Read `llms.txt` or `AGENTS.md` when the host client supports those discovery surfaces.
- Prefer `plan` when the user gives a plain-English outcome.
- Prefer `inspect` before hand-crafting a body for a specific service.
- Prefer `direct/prepare` when the user wants provider payment to come directly from their own Base or Tempo wallet.
- Prefer `run` when the user wants Enchant-funded execution rather than local wallet settlement.
- If `run` returns `paymentChoiceRequired`, ask whether to use Enchant credits or direct Base or Tempo wallet settlement, then continue with `POST /api/agent/v1/payment/resolve` using the returned `resume.resumeToken`.
- If `payment.availableExecutionModes` only includes `credits`, the selected route does not currently support direct Base or Tempo wallet settlement.
- If `run` or `payment/resolve` returns `fundingRequired`, top up the balance and continue with `POST /api/agent/v1/run/resume` using the returned `resume.resumeToken`.
- If `run`, `run/resume`, or `payment/resolve` returns a status token, keep polling `run/status` until a final result arrives.
- If `direct/prepare` succeeds, keep the signing key on the agent host and execute the prepared request locally.
- If `direct/prepare` returns `directWalletUnavailable`, fall back to Enchant-funded execution.
- Use `GET /api/agent/v1/history` or `GET /api/agent/v1/history/receipt` when you need a recent run trail or one receipt by usage event id.
- If `plan` returns `type: "clarify"`, use `clarifyKind`, `message`, and the suggestions to narrow the ask. Missing-field clarifications are only one case.
- If multiple services match in `discover`, prefer the highest-scoring result unless the user asks for a specific provider.
- Treat pricing hints as estimates, not guaranteed final cost.
- If auth is missing or the user needs a new key or more credits, send them to `{ENCHANT_BASE_URL}/agents#setup-console`.
- If the host client supports hosted OAuth for remote MCP servers, prefer that over a pasted API key.
- If the user wants client-specific setup help, send them to `{ENCHANT_BASE_URL}/agents/install`.
- If the user wants machine-readable route definitions or reusable config artifacts, send them to `{ENCHANT_BASE_URL}/api/agent/v1/openapi` and `{ENCHANT_BASE_URL}/agents/config`.

## Current Alpha Notes

- Account creation still starts in the web setup console.
- Card checkout can now be initiated through the agent funding routes, but payment still completes in hosted Stripe Checkout.
- Direct wallet execution now supports Base x402 and Tempo MPP through `direct/prepare` plus a local `ENCHANT_EVM_PRIVATE_KEY`.
- Payment-choice tokens are single-use once a valid mode is resolved.
- A small official TypeScript client asset is available at `{ENCHANT_BASE_URL}/agents/sdk/enchant-agent-client.ts`, including stateful helpers like `runUntilTerminal()` and local direct-wallet hook points.
- Some providers finish synchronously while others require polling through `run/status`.