> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rheon.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Where a submitted deposit is by receipt
> Stateless: derives the tracking reference from the source transaction hash and asks the provider that owns the route. Works for aggregator-routed transfers; a transfer whose reference lives in the receipt logs (the intents path) cannot be tracked here and is refused pointing at GET /v1/orders/{id}. The quote is required as the proof the transfer is yours.
**Production, real money.** This endpoint runs on live routes: the transaction you build moves real funds the moment the user signs it, and every hash you see is a real one. There is no crypto sandbox. Use a small amount to try it.
## OpenAPI
````yaml https://backend.rheon.io/openapi.json post /v1/deposit/status
openapi: 3.1.0
info:
title: Rheon partner API
version: 1.0.0
description: >-
The /v1 surface a partner's backend calls with an API key.
**Authentication.** Every route takes `Authorization: Bearer `. One
kind of key: it carries its permissions and limits, and works from your
server, a page, or this playground alike - where it is called from is not
checked. Treat it as a secret all the same: anyone holding it acts under its
permissions until it is rotated.
**Rate limit.** Counted per key, at the requests-per-second rate configured
on the key - never per IP, so your users do not throttle each other. Over
it: `429 rate_limited`.
**Amounts.** Token amounts are decimal strings in the token's smallest unit;
fiat amounts are decimal strings in major units. Never JSON numbers.
**Errors.** One envelope everywhere: `{ error: { code, message } }`, with
`fields` added on bank refusals that named a field. A body that is not valid
JSON answers `400 invalid_request`; an endpoint that does not exist answers
`404 not_found`; a deployment with no partner keys configured answers `404
not_configured` for all of /v1.
**Environment.** Every response carries `environment` as its first field:
`sandbox` or `production`, derived from the upstreams this deployment is
configured against (never a flag). Read it off any response you paste into a
ticket. In `sandbox` no real money moves and the card corridor is the
provider's sandbox asset, which differs from production - read it from GET
/v1/config, not from these docs.
**Card corridor.** The asset and chain a card purchase settles as are fixed
per deployment, not chosen per request. GET /v1/config reports the one
actually configured.
servers:
- url: https://api.rheon.io
description: Production
security:
- bearerAuth: []
tags:
- name: Configuration
- name: Crypto deposits
- name: Orders
- name: Cards
- name: Bank transfers
- name: Virtual accounts
- name: Reference
- name: Sandbox only
paths:
/v1/deposit/status:
post:
tags:
- Crypto deposits
summary: Where a submitted deposit is by receipt
description: >-
Stateless: derives the tracking reference from the source transaction
hash and asks the provider that owns the route. Works for
aggregator-routed transfers; a transfer whose reference lives in the
receipt logs (the intents path) cannot be tracked here and is refused
pointing at GET /v1/orders/{id}. The quote is required as the proof the
transfer is yours.
operationId: depositStatus
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DepositStatusRequest'
responses:
'200':
description: The transfer status.
content:
application/json:
schema:
$ref: '#/components/schemas/TransferStatusResult'
'400':
description: >-
Cannot answer this.
- `invalid_request`: `provider` or `receipt` is missing, or this
transfer cannot be tracked by receipt here (ask by order number
instead).
x-error-codes:
- invalid_request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: >-
No usable API key.
- `unauthorized`: Missing, malformed or unknown key. One
undifferentiated answer on purpose.
x-error-codes:
- unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'403':
description: >-
Refused by the key's scope.
- `permission_denied`: The key does not carry the `deposits`
permission.
- `quote_not_verified`: The quote does not verify or is not this
key's.
- `chain_not_allowed`: The quote's corridor is no longer on this
key's list.
x-error-codes:
- permission_denied
- quote_not_verified
- chain_not_allowed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: >-
Over this key's rate.
- `rate_limited`: More requests per second than the key is
configured for. Counted PER KEY (all your users share one bucket),
never per IP.
x-error-codes:
- rate_limited
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: >-
Our fault.
- `internal`: Unexpected server error. Detail is in our logs, never
on the wire.
x-error-codes:
- internal
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
security:
- bearerAuth: []
components:
schemas:
DepositStatusRequest:
type: object
properties:
provider:
type: string
description: The `provider` from the quote.
example: lifi-aggregator
receipt:
$ref: '#/components/schemas/TransferReceipt'
quote:
$ref: '#/components/schemas/SignedQuote'
description: >-
The quote this transfer was built from, unchanged. On /v1 the quote
is the credential that proves the transfer is yours; a status read
is answered even after the quote's price deadline has passed.
required:
- provider
- receipt
- quote
TransferStatusResult:
type: object
properties:
environment:
$ref: '#/components/schemas/Environment'
status:
$ref: '#/components/schemas/TransferStatus'
providerStatus:
description: >-
The provider's own status word, verbatim - present only when
`status` is unknown.
type: string
txHashes:
type: object
properties:
origin:
description: Transaction that started the transfer on the source chain.
type: string
delivered:
description: >-
Transaction that delivered funds on the destination chain, once
done.
type: string
additionalProperties: false
deliveredAmount:
description: >-
What the destination transaction actually paid out, as a decimal
string in the token's MAJOR unit (e.g. "100.134221"). Absent until
reported. This is the figure to reconcile against; the quote's
outAmount is a floor.
example: '100.134221'
type: string
required:
- environment
- status
additionalProperties: false
ErrorEnvelope:
type: object
properties:
environment:
$ref: '#/components/schemas/Environment'
error:
type: object
properties:
code:
type: string
description: >-
Machine-readable error code. Branch on this, never on the
message.
example: invalid_request
message:
type: string
description: Human-readable explanation. Wording may change.
example: amount must be a decimal string of the token's smallest unit.
fields:
description: >-
Per-field complaints from the bank provider, when it named the
field it refused (bank routes only). Field names, never values.
example:
applicantInfo.nationality: iso3166_1_alpha2
type: object
propertyNames:
type: string
additionalProperties:
type: string
required:
- code
- message
additionalProperties: false
required:
- environment
- error
additionalProperties: false
description: The one error shape this API produces.
TransferReceipt:
type: object
properties:
txHash:
$ref: '#/components/schemas/TxHash'
description: Hash of the source-chain transaction the user submitted.
logs:
description: >-
Receipt logs. Accepted for compatibility and IGNORED: the backend
trusts no caller's claim about what is on the chain.
type: array
items:
type: object
properties:
address:
type: string
topics:
type: array
items:
type: string
required:
- address
- topics
required:
- txHash
SignedQuote:
type: object
properties:
provider:
type: string
description: >-
Opaque identifier of the route source. Pass it back unchanged on
/v1/deposit/status.
example: sprinter
outAmount:
type: string
pattern: ^\d+$
description: >-
Expected amount delivered at the destination, smallest unit of the
destination token. Under target-out this is a FLOOR: bridges deliver
at least this, usually a little more.
example: '4999750'
validUntil:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Unix seconds after which the quote is refused with quote_expired.
Set by us: at most five minutes from issue, or the provider's sooner
deadline.
example: 1788799278
executionDurationSeconds:
description: >-
How long the provider ESTIMATES the transfer takes, in seconds. Not
a quote deadline. Absent when the provider does not state one.
type: number
payload:
description: >-
Opaque provider data needed to build the transaction. Do not inspect
or modify; its shape differs per provider and is not a contract.
rheonCorridor:
type: object
properties:
sourceChain:
$ref: '#/components/schemas/ChainId'
destChain:
$ref: '#/components/schemas/ChainId'
required:
- sourceChain
- destChain
description: >-
The chains this quote moves between, written by us and covered by
the signature. Do not alter.
rheonTransfer:
type: object
properties:
fromAddress:
$ref: '#/components/schemas/EvmAddress'
toAddress:
$ref: '#/components/schemas/EvmAddress'
sourceChain:
$ref: '#/components/schemas/ChainId'
sourceToken:
$ref: '#/components/schemas/EvmAddress'
destChain:
$ref: '#/components/schemas/ChainId'
destToken:
$ref: '#/components/schemas/EvmAddress'
amount:
type: string
pattern: ^\d+$
description: Decimal string in the token's smallest unit.
example: '4980000'
amountMode:
$ref: '#/components/schemas/AmountMode'
required:
- fromAddress
- toAddress
- sourceChain
- sourceToken
- destChain
- destToken
- amount
- amountMode
description: >-
What was asked for, echoed by us (addresses lower-cased) and covered
by the signature. Do not alter.
rheonClient:
type: string
description: >-
The API client this quote was issued to. A quote is only accepted
back by the key it was issued to.
example: acme
rheonSig:
type: string
description: >-
Our signature over every other field. A quote that does not verify,
or was altered anywhere, is refused.
example: 5cdc0af7861b267c45c0feec1cd2689278c94d70a53108c8c1226da055a6e25e
required:
- provider
- outAmount
- validUntil
- payload
- rheonCorridor
- rheonTransfer
- rheonClient
- rheonSig
description: >-
A quote we issued. Send the WHOLE object back as `quote`, exactly as
returned - every field is covered by the signature. The `environment`
field every response starts with may come back with it; it is not part
of the signature and is ignored on the way in.
Environment:
type: string
enum:
- sandbox
- production
description: >-
Which environment answered. `sandbox`: at least one money upstream is
the provider's sandbox - no real money moves there, and the card
corridor is the sandbox's asset (read GET /v1/config), not the
documented production one. `production`: every configured upstream is
real. Derived from the configured upstream hosts at boot, never a flag.
example: sandbox
TransferStatus:
type: string
enum:
- pending
- done
- failed
- expired
- refunded
- unknown
description: >-
pending: in flight. done: delivered (credit the user). failed: broke,
nothing delivered. refunded: the money went back to the sender. expired:
produced by no provider today, kept for older consumers. unknown: the
provider answered a word outside this vocabulary (see providerStatus) -
not terminal, poll again.
TxHash:
type: string
pattern: ^0x[0-9a-fA-F]{64}$
description: 0x-prefixed 32-byte transaction hash.
example: '0x1111111111111111111111111111111111111111111111111111111111111111'
ChainId:
type: integer
exclusiveMinimum: 0
maximum: 9007199254740991
description: EVM chain id, a positive integer (e.g. 42161 for Arbitrum One).
example: 42161
EvmAddress:
type: string
pattern: ^0x[0-9a-fA-F]{40}$
description: >-
EVM address: 0x followed by 40 hex characters. Checksum casing is not
required.
example: '0x1111111111111111111111111111111111111111'
AmountMode:
type: string
enum:
- exact-in
- target-out
description: >-
Which side `amount` pins down. `exact-in` (the default when omitted):
the payer spends exactly `amount` of the source token. `target-out`: at
least `amount` of the destination token must land, and the payer's side
flexes. Any other value is refused rather than defaulted.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your API key, issued by us and shown once at creation.
````