Conversions in sandbox

Every ONRAMP and OFFRAMP order includes an FX conversion leg that exchanges the source asset for the destination asset. The conversion runs automatically after the source leg settles; there is no standalone endpoint to create one. This page explains how to drive conversion failure outcomes in sandbox.

This page applies to both order shapes. An order that names a source is funded from a balance the customer already holds; an order created with no source — sending sourceAsset instead — is funded at an address Conduit publishes on the order, via POST /v2/sandbox/orders/:orderId/deposits/simulate. Both then run the same conversion leg and fail the same way. See Deposit-Funded Orders and the deposit-funded walkthrough.

The reason field is optional (max 500 chars). When supplied, it surfaces verbatim as failureMessage on the order.failed webhook payload and on the polled GET /v2/orders/:id response, with no transformation.

How to fail a conversion

Use the orders/:id/simulate/conversion-failed endpoint to force a conversion to a failed terminal state. The endpoint is timing-independent: call it at any point after order creation. If the conversion is already running, it is driven to failed immediately; otherwise the failure is armed and applied as soon as the conversion starts. The order is driven to failed and order.failed is emitted.

curl -X POST https://api.sandbox.conduit.financial/v2/sandbox/orders/$ORDER_ID/simulate/conversion-failed \
  -H "x-api-key: $SANDBOX_API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Provider rate stale"}'

const res = await fetch(
  `${process.env.SANDBOX_HOST}/v2/sandbox/orders/${orderId}/simulate/conversion-failed`,
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.SANDBOX_API_KEY!,
      "idempotency-key": crypto.randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ reason: "Provider rate stale" }),
  },
);

import httpx, os, uuid
r = httpx.post(
    f"{os.environ['SANDBOX_HOST']}/v2/sandbox/orders/{order_id}/simulate/conversion-failed",
    headers={
        "x-api-key": os.environ["SANDBOX_API_KEY"],
        "idempotency-key": str(uuid.uuid4()),
    },
    json={"reason": "Provider rate stale"},
)

Returns 200 OK with the order at its current state. Returns 404 if the order is not found. Replays against an already-terminal order return 200 with the current resource (idempotent).

Rate-lock expiry SLA. POST /v2/sandbox/orders/:id/simulate/rate-lock-expired returns 200 OK with the order at its current state and the order reaches cancelled (expired) within about 3 seconds via an immediate background sweep tick. No polling backoff needed; no need to wait for the scheduled 30-second sweep.

There is no create-time outcome locking for conversions. The only way to force a conversion failure in sandbox is this endpoint, which works at any point after the order exists.

Webhook events

Conversion outcomes surface on the order’s webhook topic. There is no standalone conversion webhook.

Event	When it fires
`order.succeeded`	The full order completed successfully (source settled, conversion ran, destination credited). Terminal.
`order.failed`	The order failed. `reasonCode` (`insufficient_funds` / `provider_unavailable` / `provider_rejected` / `internal_error` / `cancelled`) names the failure category. Conversion failures surface here.
`order.cancelled`	The order was cancelled before execution completed. `cancellationReason` is `expired` or `client_cancelled`.

Intermediate state (conversion in progress, source settled, etc.) is not conveyed via webhooks. Poll GET /v2/orders/:id to observe the current order state between terminal events. See the Webhooks reference for full payload schemas.

Errors

Conversion failures produce order.failed on the order. The payload carries reasonCode (insufficient_funds / provider_unavailable / provider_rejected / internal_error / cancelled) describing the failure category. See Error codes for the broader catalog used by other event types.

Get started

Transaction guides

References

Scenario libraries

Conversions in sandbox

How to fail a conversion

Webhook events

Errors

See also

​How to fail a conversion

​Webhook events

​Errors

​See also

How to fail a conversion

Webhook events

Errors

See also