---
title: "Record settled onramp amount for exact SA transfer"
method: POST
path: "/v1/onramp/settled"
tags: ["onramp"]
---

# Record settled onramp amount for exact SA transfer

`POST /v1/onramp/settled`

Record the exact settled amount from a completed Coinbase onramp purchase.

Called by the frontend after the user completes the Coinbase onramp UI and the
settled crypto amount is known. This transitions the onramp event from `pending`
to `confirmed`, making it available for the SA→tipping transfer step.

**Idempotent:** If the event is already consumed, returns current state without error.

**Error codes:**
- 400: Invalid settled_amount format or not positive
- 404: Event not found or doesn't belong to authenticated account
- 409: Event is stale, or has a conflicting coinbase_transaction_id

## Headers

- `authorization` string, nullable — Bearer JWT issued by Grove.

## Request body

- OnrampSettleRequest — Request model for recording settled onramp amount.
  - `event_id` string, required — Onramp event ID returned by /v1/onramp/url
  - `settled_amount` string, required — Settled USDC amount from Coinbase onramp flow
  - `coinbase_transaction_id` string, nullable — Optional Coinbase transaction ID for idempotency/correlation

## Response `200`

Successful Response

- OnrampSettleResponse — Response model for POST /v1/onramp/settled.
  - `event_id` string, required — Onramp event ID
  - `status` string, required — Event status
  - `settled_amount` string, nullable — Settled amount in token units
  - `consumed` boolean, required — Whether this event has already been consumed by transfer-complete
  - `lifecycle_state` string, nullable — Structured lifecycle state: awaiting_coinbase_completion, settlement_detected, transfer_submitted, needs_attention

## Other responses

- `400` — Invalid settled amount
- `401` — Missing or invalid JWT
- `404` — Onramp event not found
- `409` — Stale/consumed/conflicting onramp event update
- `422` — Validation Error

---

[API](https://skmtc.net/grove/apis/grove-api.md) · [All operations](https://skmtc.net/grove/apis/grove-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/grove/grove-api/versions/f286b48a8105/schema)