Order lifecycle
Save your session token, request key, operation ID, order ID and wallet transaction hashes. Resume from those records after a restart.
Retry the same request
orders, payment and action use a durable operation journal. Reuse the same idempotency_key and body after a timeout. A changed body with the same key is rejected.
A quote can create an order only once, even if you retry it with a different key. Creating a new quote starts a separate request. It doesn't resolve an uncertain earlier order.
| Operation state | What to do |
|---|---|
succeeded | Save the result and follow its next action |
running | Check operation after the suggested delay |
rejected | Read the error and correct the request; no retry with changed parameters under the same key |
unknown | Stop new order creation and funding for this request. Keep its ID and use the app's help options |
An unknown result needs reconciliation. Polling it does not cause another purchase. If you lost the response before saving an operation ID, repeat the original request with its original key. list_orders also returns your session's latest 100 saved orders.
Follow the next action
| Action type | Meaning |
|---|---|
send_deposit | Current deposit instructions; first check for a transfer you've already sent |
order | Wait for retry_after_seconds, then read the order again |
funding | Pay Mode can accept a contribution; check balance and pending transfers first |
action | Call the named action with the supplied IDs and a saved idempotency key |
hold | Read the reason and allowed resolutions; use the app for resolutions outside the API |
delivery | Retrieve delivered codes or credentials for this intent |
open_app | Continue in the order's app interface, then resume tracking |
send_deposit is offered only for an unexpired, awaiting-deposit intent without a blocking hold. Its amount accounts for detected funds, but an unconfirmed transfer may not be detected yet. Your wallet journal remains necessary.
A bridge address can outlast its quote. Read the current instructions before each transfer: the old rate may have expired, and a late or unmatched deposit may be held for your decision.
Holds and refunds
The order lists holds, their scope and allowed actions. The API supports setting a crypto refund destination and resolving a deposit hold with refund or keep_holding when that option is offered. Other resolutions continue in the app.
Setting a refund address does not itself send a refund. Track the order until the refund completes and check its evidence. A hold or service disruption is not a reason to send the original amount again.
Errors and limits
HTTP errors include a stable error.code and a message. Validation errors also identify invalid fields. Mutation outcomes can return HTTP 200 with state: "rejected" or state: "unknown"; always inspect the body. MCP marks error results with isError.
Honor HTTP Retry-After on 429 responses. Read-only requests can be retried with backoff. For mutation timeouts, use the journal rules above.
The service allows 60 private requests per session per minute and applies additional network limits. Poll one order at the returned interval rather than in a tight loop.
Service status explains active incidents. Use the app's help options for an unresolved order. Don't post private order links or credentials in a public channel.