# Ripple Mint API

API operations for programmatic integration with Ripple Mint.

Covers transaction queries for issuance, redemption and bridge activity; the fiat instructions
that bind a payment memo to an incoming wire, along with the Ripple bank account to send it to;
the wallets and cash accounts registered against your stablecoin product; the Ripple-owned
on-chain destinations you redeem to; and public market cap endpoints for RLUSD supply data.


Version: 1.0.0

## Servers

```
https://api.ripple.com
```

## Security

### oauth2

Type: oauth2

## Download OpenAPI description

[Ripple Mint API](https://docs.ripple.com/_bundle/@l10n/pt-BR/products/stablecoin/api/reference/rlusd-openapi.yaml)

## Authentication

Use this API operation to manage your authentication tokens.

| Operation | Method | Description |
| --------- | ------ | ----------- |
| [Obtain an access token](#operation/getAccessToken) | POST | Request an access token for authentication with the API. |


### Obtain an access token

 - [POST /v2/oauth/token](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/authentication/getaccesstoken.md): OAuth 2.0 Client Credentials grant. Returns a Bearer token valid for 1 hour.
Credentials may be passed in the request body or via HTTP Basic Auth header.

## Transactions

Use these API operations to obtain details about transactions.

| Operation | Method | Description |
| --------- | ------ | ----------- |
| [List transactions](#operation/listTransactions) | GET | Get a paginated list of transactions, optionally filtered by type and status. |
| [Get a transaction](#operation/getTransaction) | GET | Get a specific transaction by ID. |
| [Approve a pending redemption](#operation/updateTransactionDestination) | PUT | Approve a transaction held in `PENDING` status and direct it to fiat or a bridge. |


### List transactions

 - [GET /v1/stablecoin/transactions](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/transactions/listtransactions.md): Returns a paginated list of transactions, optionally filtered by types and statuses.

### Get a transaction

 - [GET /v1/stablecoin/transactions/{id}](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/transactions/gettransaction.md): Returns a single transaction by ID.

### Approve a pending redemption

 - [PUT /v1/stablecoin/transactions/{id}/destination](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/transactions/updatetransactiondestination.md): Approves a transaction held in PENDING status (flexible redemption) and directs it.
Set type to FIAT to settle to your default bank account (creates a REDEMPTION), or
to CRYPTO with a walletRipId to bridge to one of your wallets (creates a BRIDGE).

Re-submitting the same destination after the transaction has moved to PROCESSING is
idempotent and returns 200. Submitting a different destination, or approving a
transaction that was never PENDING, returns 409.

## Fiat instructions

Use these API operations to pre-declare an incoming fiat payment, obtain the memo that
correlates it to the resulting mint, and read the Ripple bank account to send it to.

| Operation | Method | Description |
| --------- | ------ | ----------- |
| [Create a buy instruction](#operation/createFiatInstruction) | PUT | Declare an incoming fiat payment under an id you choose, and receive the memo to quote on it. |
| [Get a fiat instruction](#operation/getFiatInstruction) | GET | Get a specific instruction, buy or redemption, by ID. |
| [List fiat instructions](#operation/listFiatInstructions) | GET | Get a paginated list of your instructions. |
| [Delete a buy instruction](#operation/deleteFiatInstruction) | DELETE | Retire an unused buy instruction. |
| [Get bank details](#operation/getFiatBankDetails) | GET | Get the Ripple bank account to wire the fiat to, on its own. |


### Get bank details

 - [GET /v1/stablecoin/fiat-bank-details](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/fiat-instructions/getfiatbankdetails.md): Returns the Ripple bank account to wire fiat to when buying stablecoin - the same object
embedded as bankDetails on every fiat instruction, served on its own.

The bank belongs to your account rather than to any one instruction, so this is the endpoint
to call when you want the wire destination without creating or listing an instruction:
rendering a "where to send funds" panel, caching the details, or checking them on a
schedule.

This endpoint does not return a memo. A memo is per-payment and comes only from a fiat
instruction; the bank details alone are not enough to have a payment attributed. Create an
instruction for every payment you intend to send.

Unlike the embedded bankDetails field, which is simply absent on any failure so that the
instruction and its memo still come back, this endpoint keeps its failures apart: a 404 is
a settled answer and retrying will not change it, a 502 is transient.

### List fiat instructions

 - [GET /v1/stablecoin/fiat-instructions](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/fiat-instructions/listfiatinstructions.md): Returns a paginated list of your fiat instructions, both buy (CRYPTO destination) and
redemption (FIAT destination). Deleted instructions are excluded.

bankDetails is identical on every instruction in the page - it is resolved from your
account, not from the instruction row.

### Create a buy instruction

 - [PUT /v1/stablecoin/fiat-instructions/{id}](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/fiat-instructions/createfiatinstruction.md): Declares an incoming fiat payment under an id you choose, and returns the memo to quote in
that payment's reference field so the funds can be attributed and the RLUSD minted to the
wallet you named.

You generate the UUID for {id} client-side and it becomes the instruction's identity.
Reusing an id that already exists is rejected with a 409 carrying code
FIAT_INSTRUCTION_ALREADY_EXISTS.

Only a CRYPTO destination may be created here. Redemption (FIAT) instructions are
created by Ripple when your redemption is registered, and are read-only to you.

> Put the memo verbatim into the payment's reference field, and nothing else. A
> RIPxxxxxxx wallet ripId token in the payment's free text takes precedence over a memo
> during matching, which would credit that wallet and leave this instruction UNUSED.

### Get a fiat instruction

 - [GET /v1/stablecoin/fiat-instructions/{id}](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/fiat-instructions/getfiatinstruction.md): Returns a single fiat instruction by id, including its memo and current status. Works for
both buy and redemption instructions belonging to your account.

Only your own instructions are visible. An id belonging to another customer, a deleted
instruction, and an id that never existed are all reported as
404 FIAT_INSTRUCTION_NOT_FOUND.

### Delete a buy instruction

 - [DELETE /v1/stablecoin/fiat-instructions/{id}](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/fiat-instructions/deletefiatinstruction.md): Retires a buy instruction you no longer intend to use, so a fiat payment arriving later with
its memo can never mint against it. Because instructions never expire, this is the only way
to retire an unused one - an abandoned instruction left alone stays UNUSED and claimable
indefinitely.

Deletion is permanent and there is no un-delete: create a new instruction with a new id,
which gets a new memo. Transactions already produced from the instruction are unaffected and
keep their fiatInstructionId and memo.

Only your own UNUSED buy instructions can be deleted. A redemption (FIAT) instruction is
reported as 404, since this operation only addresses your CRYPTO instructions.

## Wallets

Use this API operation to resolve the wallets registered for your tenant - the `ripId`
values you quote as `walletRipId` elsewhere in this API.

| Operation | Method | Description |
| --------- | ------ | ----------- |
| [List wallets](#operation/listWallets) | GET | Get a paginated list of your wallets, optionally filtered by `ripId`. |


### List wallets

 - [GET /v1/stablecoin/wallets](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/wallets/listwallets.md): Returns a paginated list of the wallets registered for your tenant. This is the ripId
lookup: use it to resolve the walletRipId you quote on a fiat buy instruction or a bridge
approval, and to map a walletRipId on a transaction leg back to an address and chain.

A ripId that matches nothing returns an empty page with 200, never a 404.

## Bank accounts

Use this API operation to obtain the cash accounts registered against your stablecoin product,
including the one your `FIAT` redemptions settle to.

| Operation | Method | Description |
| --------- | ------ | ----------- |
| [List bank accounts](#operation/listBankAccounts) | GET | Get a paginated list of your stablecoin bank accounts. |


### List bank accounts

 - [GET /v1/stablecoin/bank-accounts](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/bank-accounts/listbankaccounts.md): Returns a paginated list of the cash accounts registered against your stablecoin product,
including which one your FIAT redemptions settle to (isRedemption).

Account numbers and IBANs are served redacted to their last four characters. For the Ripple
account to wire into when buying, which is served in full, see
Get bank details.

An account list with no rows returns an empty page with 200, never a 404.

## Crypto instructions

Use this operation to obtain the Ripple-owned on-chain addresses to which you send RLUSD for redemption/bridging.

| Operation | Method | Description |
| --------- | ------ | ----------- |
| [List crypto instructions](#operation/listCryptoInstructions) | GET | Get the distinct redemption destinations for your tenant. |


### List crypto instructions

 - [GET /v1/stablecoin/crypto-instructions](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/crypto-instructions/listcryptoinstructions.md): Returns the distinct Ripple-owned on-chain destinations to which the authenticated tenant
sends RLUSD for redemption/bridging. An empty or cold cache returns an empty page with 200 OK.

## Market Cap

Use these API operations to obtain details about market-capitalization supply for a stablecoin currency.

| Operation | Method | Description |
| --------- | ------ | ----------- |
| [Get total supply](#operation/getMarketCapTotal) | GET | Get the total amount of currency supply, with a per-chain breakdown. |
| [Get total supply amount](#operation/getMarketCapTotalAmount) | GET | Get the total supply as a plain decimal string. |
| [Get circulating supply](#operation/getMarketCapCirculating) | GET | Get the circulating amount of currency supply, with a per-chain breakdown. |
| [Get circulating supply amount](#operation/getMarketCapCirculatingAmount) | GET | Get the circulating supply as a plain decimal string. |

**Note:** These Market Cap operations do not require authentication.


### Get total supply

 - [GET /v1/stablecoin/market-cap/{currencyCode}/total](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/market-cap/getmarketcaptotal.md): Returns the total RLUSD supply (all issued tokens, regardless of circulating status)
with a per-chain breakdown. No authentication required.

### Get total supply amount

 - [GET /v1/stablecoin/market-cap/{currencyCode}/total/amount](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/market-cap/getmarketcaptotalamount.md): Returns the total RLUSD supply as a plain decimal string (e.g. "1000000000.00").
Useful for lightweight integrations that only need the aggregate figure.
No authentication required.

### Get circulating supply

 - [GET /v1/stablecoin/market-cap/{currencyCode}/circulating](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/market-cap/getmarketcapcirculating.md): Returns the circulating RLUSD supply with a per-chain breakdown.
Returns 404 if the circulating supply API is not enabled.
No authentication required.

### Get circulating supply amount

 - [GET /v1/stablecoin/market-cap/{currencyCode}/circulating/amount](https://docs.ripple.com/pt-br/products/stablecoin/api/reference/rlusd-openapi/market-cap/getmarketcapcirculatingamount.md): Returns the circulating RLUSD supply as a plain decimal string.
Returns 404 if the circulating supply API is not enabled.
No authentication required.