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

# Crypto Deposit Addresses

> Requesting deposit addresses for supported settlement rails and chains.

Request one deposit address for the chain you selected. The API creates or returns the address for your Stabyl account on that route. Addresses are requested on demand, so you do not need to create addresses across every supported chain before the user chooses a route.

Production requires approved KYB before this endpoint returns an existing
address or provisions a new one. A non-approved account receives `403`, even if
an address was provisioned previously. Development and staging skip this gate.

```bash theme={null}
curl "https://api-staging.stabyl.com/v1/partner/wallets/crypto/address?chain=tron" \
  -H "X-Api-Key: $STABYL_API_KEY"
```

## Response Handling

Store the chain and address together. When displaying deposit instructions, show the exact chain returned by the API next to the address. If your interface has QR codes, encode only the returned address and keep the chain label visible outside the QR code.

```json theme={null}
{
  "status": "success",
  "data": {
    "chain": "tron",
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "currency": "USD",
    "settlement_rails": ["USDT"]
  }
}
```

The response fields may include additional route metadata. Preserve unknown fields safely in logs or diagnostics only if your data policy allows it; do not build hard dependencies on fields that are not documented for your workflow.

## Safety Rules

* Use the chain value returned by `GET /partner/wallets/chains`.
* Show the exact returned chain and address.
* Sending funds on a different chain can permanently lose funds.
* In development testing, Tron Nile is the preferred USDT route.
* Do not rewrite, trim, or normalize crypto addresses beyond basic whitespace handling.
* Save the chain alongside every address, deposit record, and support ticket reference.

Crypto deposits credit the USD wallet after confirmation and any required
compliance checks. `USDT` and `USDC` are stablecoin rails for USD activity.
If a deposit needs Travel Rule information, wallet transaction reads return
`status: "hold"` with `required_action.type: "travel_rule"` until the user
submits the requested sender details through
`POST /partner/wallets/crypto/deposits/{id}/travel-rule`.

## Deposit States

| State      | Meaning                                                                                |
| ---------- | -------------------------------------------------------------------------------------- |
| pending    | Deposit has been detected or is waiting for confirmation                               |
| processing | Deposit is progressing and is not yet available                                        |
| hold       | Deposit is confirmed but waiting for compliance clearance or required user information |
| success    | Deposit has been credited and is available                                             |
| failed     | Deposit could not be credited                                                          |

Use deposit webhooks for timely changes and wallet transaction reads for
periodic reconciliation and webhook-gap recovery.

Common failures include unsupported chain values, missing `X-Api-Key`, or requesting an address before wallet access is enabled.