Authentication and scope
On the signed-in Agents screen, enter an Agent name and select Create agent key. The secret is shown once. Store it as a secret in the agent's environment, not in source code, browser code, screenshots, or logs. Send it in the Authorization: Bearer <key> header for every /v1/ request.
Each key belongs to one wallet and can read only requests created with that agent. It cannot call the owner's payment endpoints or approve in the wallet. Disconnecting the agent in Edith revokes the key.
Create a request
POST /v1/requests accepts JSON with one field, url. Use an HTTPS paid API address that Edith can reach. The response is a JSON record of the decision. The call itself never spends SUI.
curl -X POST 'https://edith-sooty.vercel.app/v1/requests' \
-H 'Authorization: Bearer YOUR_AGENT_KEY' \
-H 'Content-Type: application/json' \
--data '{"url":"https://edith-sooty.vercel.app/demo/quote?ticker=SUI"}'The Quote Desk URL is the bundled Mainnet demo provider. If the request is payable, its state is awaiting. The wallet owner must still approve its 0.001 SUI quote plus network fees.
Read a result or withdraw a request
Use GET /v1/requests/:id with the same key to poll the request. An agent may withdraw an awaiting request with POST /v1/requests/:id/cancel. Cancellation cannot undo a payment that has started.
curl 'https://edith-sooty.vercel.app/v1/requests/REQUEST_ID' \
-H 'Authorization: Bearer YOUR_AGENT_KEY'Read the response states
| State | What it means | Agent action |
|---|---|---|
awaiting | A priced request needs owner review. approval.review is the review URL. | Show the URL and poll. Do not assume approval. |
blocked | Memory, a price rule, or a limit refused it before payment. | Read decision.reason; do not retry blindly. |
free | The provider returned data without payment. | Read status and body. |
settling | A signed payment is being processed. | Keep polling. |
paid | Payment was verified. The response may still be useful or worthless. | Inspect result, body, digest, and blobId. |
uncertain | The signed payment might still settle. | Tell the owner to use Check Sui again; do not submit a replacement payment. |
cancelled, expired, failed, refused | The request ended without a successful provider payment. | Read error or the decision; ask again only when appropriate. |
Amounts are returned as amountMist, a decimal string in MIST. One SUI is 1,000,000,000 MIST. A paid record can include a digest for Sui and a blobId for Walrus Memory. If saving memory failed after settlement, the payment can still be paid without a blob ID.
A practical agent loop
Set EDITH_AGENT_KEY as a secret in your shell or runtime. Edith includes a small reference client, src/agent.mjs, that creates a request, polls while it is waiting or settling, and prints the result.
# Set EDITH_AGENT_KEY in your environment first.
EDITH_URL=https://edith-sooty.vercel.app \
npm run agent -- 'https://edith-sooty.vercel.app/demo/quote?ticker=SUI'When the client prints an approval URL, the owner opens it in Edith, reviews the quote, and decides in the wallet. The agent polls until the record is final or its own wait period ends. A client timeout is not proof that an on-chain payment failed.
HTTP errors
Non-2xx responses contain {"error":"..."}. An invalid or revoked key returns 401, a request outside the agent's scope returns 404, an unsafe or unquotable request can return 422, and request throttling returns 429. Treat these as errors, separate from a successful 200 response whose state is blocked.