> ## Documentation Index
> Fetch the complete documentation index at: https://docs.copby.digitalcop.shop/llms.txt
> Use this file to discover all available pages before exploring further.

# Arc to COPm settlement

> Quote USDC on Arc and create a settlement order that delivers COPm to a Celo wallet.

COP By prepares settlement orders that start with USDC on Arc and end with COPm at an EVM address on Celo.

```text theme={null}
Arc USDC
  → Circle CCTP Standard Transfer
  → Arbitrum USDC
  → Squid
  → Celo USDm
  → Mento
  → COPm destination
```

> [!WARNING]
>
> An organization must activate and fund its Arbitrum settlement account before creating an
> order. COP By uses that account to receive the CCTP mint and execute the route to Celo.

## Product rules

| Rule | Value |
| - | - |
| Source | USDC on Arc |
| Destination | Any valid EVM address on Celo |
| Minimum principal | 10 USDC |
| Maximum principal | 1,000 USDC |
| Quote lifetime | 60 seconds |
| COP By fee | 1% by default; configurable |
| Squid route slippage | 3% |
| Maximum accepted route variance | 4% |
| Circle transfer | CCTP Standard Transfer with Forwarding Service |

The Circle forwarding fee is charged in addition to the principal. The quote returns both
`circleUpfrontFeeUsdc` and `totalDebitUsdc`. Squid costs remain included in the route output and
are not presented as a separate customer fee.

## Create a quote

```bash theme={null}
curl --request POST \
  --url https://api.copby.digitalcop.shop/api/integrations/settlements/quotes \
  --header 'Authorization: Bearer copby_live_pk_...' \
  --header 'Content-Type: application/json' \
  --data '{
    "sendAmountUsdc": "50",
    "sourceAddress": "0x2222222222222222222222222222222222222222",
    "destinationAddress": "0x3333333333333333333333333333333333333333"
  }'
```

`sendAmountUsdc` is the exact principal covered by the Circle quote. The user debit is:

```text theme={null}
totalDebitUsdc = sendAmountUsdc + circleUpfrontFeeUsdc
```

`copAmountMin` is the binding delivery floor. Create the order before `expiresAt`; otherwise request
a new quote.

## Create an order

Use a unique `Idempotency-Key` for every logical order. Retrying the same key and quote returns the
same order. Reusing the key for a different quote returns `IDEMPOTENCY_CONFLICT`.

```bash theme={null}
curl --request POST \
  --url https://api.copby.digitalcop.shop/api/integrations/settlements/orders \
  --header 'Authorization: Bearer copby_live_pk_...' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: deposit-2026-09-23-001' \
  --data '{
    "quoteId": "qst_example",
    "reference": "customer-deposit-1042"
  }'
```

Creating an order does not move funds. Its `execution` response contains the Arc calls for the
user's wallet:

* Use `atomicBatch.calls` with `wallet_sendCalls` when the wallet supports batching. This gives
  the user one confirmation.
* Otherwise, submit `sequential.calls` in order. The plan omits `approve` when the existing USDC
  allowance covers `totalDebitUsdc`.

After the burn confirms on Arc, report its transaction hash to COP By. The burn is verified against
the order and immediately triggers settlement. A scheduled worker retries pending orders as a
fallback.

```bash theme={null}
curl --request POST \
  --url https://api.copby.digitalcop.shop/api/integrations/settlements/orders/ord_example/burn \
  --header 'Authorization: Bearer copby_live_pk_...' \
  --header 'Content-Type: application/json' \
  --data '{ "txHash": "0x..." }'
```

COP By then waits for Circle Forwarding to mint USDC to the organization settlement account on
Arbitrum, obtains a fresh Squid route, and verifies the final COPm transfer on Celo. Poll the order
until it reaches `DELIVERED`.

## Read an order

```bash theme={null}
curl --request GET \
  --url https://api.copby.digitalcop.shop/api/integrations/settlements/orders/ord_example \
  --header 'Authorization: Bearer copby_live_pk_...'
```

Orders are isolated by organization. An API key cannot read an order owned by another integration.

## Errors

Settlement errors include lifecycle context instead of a generic message:

```json theme={null}
{
  "error": {
    "code": "QUOTE_EXPIRED",
    "message": "La cotizacion expiro.",
    "stage": "CREATED",
    "fundsStatus": "IN_USER_WALLET",
    "fundsMoved": false,
    "retryable": true,
    "nextAction": "CREATE_NEW_QUOTE"
  }
}
```

`SETTLEMENT_ACCOUNT_INACTIVE` means the organization must activate and fund its settlement account
before creating an order. A route above the 4% guard returns `SLIPPAGE_LIMIT_EXCEEDED`; COP By does
not proceed to burn. If an order becomes `STUCK`, continue polling it and contact support with the
order ID; automated refunds are not part of this release.

## Settlement boundary

COP By considers a settlement delivered only after COPm is verified at the requested Celo address.
Depositing those COPm into Neeru or another protocol is outside this settlement order and requires a
separate integration.

> [card] [Errors and lifecycle](https://docs.copby.digitalcop.shop/errors-lifecycle.md)
>
> Handle quote expiry, intake pauses, stuck orders, and safe retries.

> [card] [API reference](https://docs.copby.digitalcop.shop/api-reference)
>
> Inspect settlement request and response schemas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.