> ## Documentation Index > Fetch the complete documentation index at: https://direct-api.reap.global/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve funding instructions and Treasury history > Get the wallet address or bank details that make up the funding information for your account, confirm bank transfers, and follow every movement in and out of your Treasury from your own tools. ## What you'll build This guide follows one use case: **getting the funding information for your card collateral** from your own system. Your card credit limit is backed by the funds you send to Reap, so adding collateral is how you raise it. By the end, your system will be able to: 1. **Find out how you can fund your card collateral**: which stablecoins, networks and bank transfers are available to your business. 2. **Retrieve the funding instructions**: a wallet address for stablecoins, or bank details and a Reference ID for a bank transfer. 3. **Confirm a bank transfer** so Reap can match it to your account. 4. **Follow your Treasury history** to see when the funds have landed. 5. **Check your card credit** to see the new credit limit. This is the "when our card credit runs low, our treasury tool fetches Reap's funding details, sends USDC from our exchange (or a bank transfer from our bank), and checks that the funds landed and our credit limit went up, without anyone logging in to the Business Account dashboard" use case. The API never moves money. It tells you where and how to send it, and shows you what moved. The transfer itself happens in your exchange, wallet or bank, as it does today. The concepts behind each step are covered in [Treasury](/concepts/treasury/overview.md), [Funding methods](/concepts/treasury/funding.md) and [Treasury transactions](/concepts/treasury/transactions.md). ## How it works **Stablecoins** ```mermaid theme={"system"} sequenceDiagram participant You as Your backend participant API as Business Account API participant Ex as Your exchange or wallet You->>API: GET /treasury/funding-options (how can I fund Card?) You->>API: GET /treasury/funding-instructions (Card, crypto, Ethereum) API-->>You: wallet address, accepted stablecoins, minimum You->>Ex: Send USDC on Ethereum to the wallet address Ex-->>You: transaction hash loop Every 30–60 seconds You->>API: GET /treasury/transactions (Card) end API-->>You: row with your transaction hash, status COMPLETED You->>API: GET /cards/balances (has my credit limit changed?) ``` **Bank transfer** ```mermaid theme={"system"} sequenceDiagram participant You as Your backend participant API as Business Account API participant Bank as Your bank You->>API: GET /treasury/funding-instructions (Card, bank transfer, HKD) API-->>You: bank details + Reference ID You->>Bank: Transfer HKD with the Reference ID in the remarks You->>API: POST /treasury/bank-transfer-confirmations API-->>You: PENDING (Reap starts verifying) loop Every few minutes You->>API: GET /treasury/transactions (Card) end API-->>You: row with your Reference ID, COMPLETED (a few minutes after the funds land in Reap's bank account) You->>API: GET /cards/balances (has my credit limit changed?) ``` | Step | What you do | Endpoint | Scope needed | | - | - | - | - | | 1 | See how you can fund Card | [`GET /treasury/funding-options`](/api-reference/treasury/list-treasury-funding-options) | `treasury_funding:read` | | 2 | Retrieve the funding instructions | [`GET /treasury/funding-instructions`](/api-reference/treasury/get-treasury-funding-instructions) | `treasury_funding:read` | | 3 | Make the transfer | In your exchange, wallet or bank | none | | 4 | Confirm the transfer (bank transfers only) | [`POST /treasury/bank-transfer-confirmations`](/api-reference/treasury/confirm-a-bank-transfer) | `treasury_funding:write` | | 5 | Check the funds landed | [`GET /treasury/transactions`](/api-reference/treasury/list-treasury-transactions) | `treasury_transactions:read` | | 6 | Check your card credit | [`GET /cards/balances`](/api-reference/cards/retrieve-card-account-balances) | `card_account_balances:read` | > **HyperEVM deposits:** use HyperEVM, not HyperCore. Sending to HyperCore cannot be recovered. Follow the warning in the funding instructions response. ## Key concepts **The API gives instructions, it doesn't move money.** Retrieving crypto instructions creates a wallet for the requested product and network if one doesn't exist. It never moves money, and confirming a bank transfer doesn't credit your account. Funds are credited only once they land in Reap's bank account. See [Treasury](/concepts/treasury/overview.md). **One wallet address per network.** On a given network, your Card wallet address accepts every stablecoin listed for it, for example USDC and USDT on Ethereum. The address stays the same every time you ask for it. Networks, currencies and minimums are listed in [Funding](/concepts/treasury/funding.md). **A new Reference ID for every bank transfer.** Each time you retrieve bank instructions you get a new Reference ID, in the format `IBM-` followed by six characters. It's how Reap matches your transfer to your account, so use one per transfer. **The Reference ID decides how fast a bank transfer is credited.** Reconciliation starts once the funds land in Reap's bank account; your bank's own processing time comes on top. With the Reference ID in the transfer remarks, the funds are reconciled and credited automatically within **a few minutes**. Without it, the Reap team reconciles the funds manually, which **can take 1 to 2 business days**. **Your Treasury history is the source of truth.** Every movement in and out of your card collateral shows up in your Treasury history: funding, repayments, adjustments and more. Crypto rows carry the blockchain transaction hash, bank transfer rows carry the Reference ID, so you can match each one to what you sent. Statuses, types, directions and filters are in [Treasury transactions](/concepts/treasury/transactions.md). **`COMPLETED` is not the same as spendable.** A `COMPLETED` row means the Treasury movement is complete. Check your card balances before issuing cards against the new funds. ## Before you begin * **Business Account API access is enabled** for your business. Ask your Reap account manager. * **A team administrator has created an API key** with these scopes: `treasury_funding:read`, `treasury_transactions:read`, `card_account_balances:read` and, for bank transfers, `treasury_funding:write`. See [Authentication](/api-reference/authentication.md). * **For bank transfers, you send from an account in your business's registered name**, as recorded in Reap. Transfers from a parent company or a payment processor aren't accepted. For supported currencies and how fiat funding works, see [How to add funds to your Reap Account?](https://support.reap.global/hc/en-us/articles/16170706183567-How-to-add-funds-to-your-Reap-Account) in the Help Center. * **The person who created the API key is still an approved team member.** Bank transfer confirmations are recorded under their name. ```bash theme={"system"} export REAP_API="https://api.global.direct.reap.global/2026-07-13" export REAP_KEY="your-api-key" # load from a secrets manager in production ``` ## Use case 1: Get the funding information for a stablecoin deposit Example: you send USDC on Ethereum from your exchange account. **1. See how you can fund Card** ```bash theme={"system"} curl "$REAP_API/treasury/funding-options" -H "x-api-key: $REAP_KEY" ``` ```json theme={"system"} { "items": [ { "product": "CARD", "methods": [ { "type": "CRYPTO", "network": "ETHEREUM", "networkName": "Ethereum (ERC-20)", "currencies": ["USDC", "USDT"] }, { "type": "CRYPTO", "network": "SOLANA", "networkName": "Solana (SPL)", "currencies": ["USDC", "USDT"] }, { "type": "CRYPTO", "network": "TRON", "networkName": "TRON (TRC20)", "currencies": ["USDT"] }, { "type": "BANK_TRANSFER", "network": "FPS", "networkName": "FPS", "currencies": ["HKD"] } ] } ] } ``` * **Only the methods your business can use are returned.** If a network isn't listed, don't send funds on it. * **Each crypto method is one network,** with the stablecoins its address accepts in `currencies`. * Show `networkName` to your users. It's the same label as in the dashboard. **2. Retrieve the wallet address for Ethereum** ```bash theme={"system"} curl "$REAP_API/treasury/funding-instructions?product=CARD&type=CRYPTO&network=ETHEREUM" \ -H "x-api-key: $REAP_KEY" ``` ```json theme={"system"} { "status": "READY", "product": "CARD", "type": "CRYPTO", "currency": null, "network": "ETHEREUM", "networkName": "Ethereum (ERC-20)", "instructions": { "walletAddress": "0x1234567890aBcDeF1234567890aBcDeF12345678", "memo": null, "supportedCurrencies": ["USDC", "USDT"], "minimumAmounts": [ { "amount": "2.00", "currency": "USDC" }, { "amount": "2.00", "currency": "USDT" } ], "estimatedCreditMinutes": 5, "estimatedRates": [ { "currency": "USDC", "targetCurrency": "HKD", "rate": "7.81" }, { "currency": "USDT", "targetCurrency": "HKD", "rate": "7.83" } ], "ratesAsOf": "2026-10-01T03:00:00.000Z" }, "retryAfterSeconds": null, "message": null } ``` | Field | What it tells you | | - | - | | `walletAddress` | Where to send the funds, on Ethereum only | | `supportedCurrencies` | The stablecoins this address accepts | | `minimumAmounts` | The smallest transfer that gets credited, per stablecoin | | `estimatedCreditMinutes` | How long the funds usually take to show in your Treasury history | | `estimatedRates` | Indicative rate into your card balance currency (here 1 USDC ≈ HKD 7.81). The rate applied can differ. If estimates are unavailable, `estimatedRates` and `ratesAsOf` are `null`; you can still use the READY wallet address | ### If the wallet is still being created If your business has never used this network, Reap creates the wallet when you first ask for it. On most networks that's instant. On Solana it can take a few minutes, and you get this instead: ```json theme={"system"} { "status": "IN_PROGRESS", "instructions": null, "retryAfterSeconds": 10, "message": "Generating your network details…" } ``` Wait `retryAfterSeconds`, then call again until `status` is `READY`. Never send funds before you have a `READY` address. **3. Send the stablecoins** This happens outside the API, in your exchange or wallet: send USDC or USDT on **Ethereum** to the `walletAddress`. Keep the **transaction hash** your exchange gives you. You'll use it to find the transfer in the next step. > [!WARNING] > > * **Send on the network you requested only.** Funds sent on another network may be lost. > * **Send only a currency in `supportedCurrencies`.** Other assets may be lost. > * **Send at least the minimum amount.** Transfers below it aren't credited and can't be refunded. **4. Check the funds landed** Funds usually show in your Treasury history within `estimatedCreditMinutes`. Poll your Card history, newest first: ```bash theme={"system"} curl "$REAP_API/treasury/transactions?product=CARD&type=DEPOSIT&from=2026-10-01" \ -H "x-api-key: $REAP_KEY" ``` ```json theme={"system"} { "items": [ { "id": "ttx_1Ab2Cd3Ef4Gh5Ij6Kl7Mn8Op", "product": "CARD", "type": "DEPOSIT", "status": "COMPLETED", "direction": "CREDIT", "amount": { "amount": "10000.000000", "currency": "USDC" }, "fee": null, "creditedAmount": { "amount": "78100.000000", "currency": "HKD" }, "conversionRate": "7.81", "method": { "type": "CRYPTO", "network": "ETHEREUM" }, "transactionHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890", "referenceId": null, "createdAt": "2026-10-01T03:02:10.000Z", "completedAt": "2026-10-01T03:04:55.000Z" } ], "meta": { "totalItems": 1, "itemCount": 1, "itemsPerPage": 20, "totalPages": 1, "currentPage": 1 } } ``` * **Find your transfer by `transactionHash`.** It's the same hash your exchange gave you. * **`creditedAmount` is what was added to your card collateral**, in your card balance currency, after conversion at `conversionRate`. * **`PENDING` means Reap has seen it but it isn't complete yet.** Keep polling until `COMPLETED`. * **Rejected Card deposits are removed from the history and never appear as `REJECTED` or `FAILED`.** A missing row alone doesn't prove rejection; check all pages and the date filters. `REJECTED`, `FAILED`, `REQUESTED`, `APPROVED`, `INVALID` and `NONE` can appear on other products (for example Optimize swaps) and are not accepted by the `status` filter, which takes `PENDING` or `COMPLETED` only. * **Poll every 30–60 seconds.** If the transfer is still `PENDING`, hasn't appeared, or is no longer listed 30 minutes after it was sent, contact Reap support with the transaction hash. * `from` and `to` are **inclusive UTC calendar days**. Results are paginated: keep requesting `page` until `meta.totalPages`. **5. Check your card credit** ```bash theme={"system"} curl "$REAP_API/cards/balances" -H "x-api-key: $REAP_KEY" ``` ```json theme={"system"} { "availableCredit": { "amount": "251100.00", "currency": "HKD" }, "totalCreditLimit": { "amount": "328100.00", "currency": "HKD" }, "allocatedCredit": { "amount": "7270.82", "currency": "HKD" }, "unallocatedCredit": { "amount": "243829.18", "currency": "HKD" }, "outstandingBalance": { "amount": "77000.00", "currency": "HKD" }, "pendingAmount": { "amount": "0.00", "currency": "HKD" } } ``` Compare `totalCreditLimit` and `availableCredit` with the values you saved before sending the funds. Once they've gone up, the new collateral is usable and you can issue cards against it. See [Issue cards to your team](/guides/issue-cards-to-your-team.md). ## Use case 2: Get the funding information for a bank transfer Example: you send HKD by FPS from your business's bank account. **1. Retrieve the bank details and a Reference ID** ```bash theme={"system"} curl "$REAP_API/treasury/funding-instructions?product=CARD&type=BANK_TRANSFER&network=FPS¤cy=HKD" \ -H "x-api-key: $REAP_KEY" ``` ```json theme={"system"} { "status": "READY", "product": "CARD", "type": "BANK_TRANSFER", "currency": "HKD", "network": "FPS", "networkName": "FPS", "instructions": { "beneficiaryName": "Reap Technologies Limited", "beneficiaryAddress": "28/F, 1063 King's Road, Quarry Bay, Hong Kong", "bankName": "Example Bank (Hong Kong) Limited", "swiftCode": "EXBKHKHH", "bankCode": "999", "branchCode": "001", "accountNumber": "123456789", "accountNumberType": "ACCOUNT_NUMBER", "bankAddress": "1 Example Street, Central, Hong Kong", "referenceId": "IBM-ABCDEF", "referenceRequired": true, "expiresAt": null }, "retryAfterSeconds": null, "message": null } ``` **Save the `referenceId` against this transfer** in your system before you send anything. Every call returns a new one, so don't call again for the same transfer. **2. Make the transfer** This happens outside the API, in your bank. Send the HKD to the account in `instructions`. > [!WARNING] > > **Include the Reference ID: it's the difference between a few minutes and 1 to 2 business days.** > > | Your transfer | Reconciled | > | - | - | > | With the exact `referenceId` in the Reference or Remarks field | Automatically, **within a few minutes** of the funds landing in Reap's bank account | > | Without the Reference ID | Manually by the Reap team, which **can take 1 to 2 business days** | > > For Reap to reconcile your transfer automatically: > > * **Put the exact `referenceId` (for example `IBM-ABCDEF`) in the Reference or Remarks field** of the transfer. > * **Send from a bank account in your business's registered name in Reap.** Transfers from another company, a parent company or a payment processor can't be matched to your account. > * **Use one Reference ID per transfer.** Don't reuse a Reference ID, and don't split one transfer across several. > * **Send the currency you requested** (here HKD). **3. Confirm the transfer to Reap** Once the transfer is sent, tell Reap with the amount and the Reference ID. This is the same as clicking **I have transferred** in the dashboard: it tells Reap a transfer is on its way. Confirming does not reconcile or credit anything. ```bash theme={"system"} curl -X POST "$REAP_API/treasury/bank-transfer-confirmations" \ -H "x-api-key: $REAP_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: card-funding-IBM-ABCDEF" \ -d '{ "product": "CARD", "network": "FPS", "amount": { "amount": "100000.00", "currency": "HKD" }, "referenceId": "IBM-ABCDEF" }' ``` ```json theme={"system"} { "id": "ttx_9Zx8Yv7Wu6Ts5Rq4Pn3Ml2Kj", "product": "CARD", "status": "PENDING", "amount": { "amount": "100000.00", "currency": "HKD" }, "referenceId": "IBM-ABCDEF", "createdAt": "2026-10-01T03:00:00.000Z" } ``` | Field | Rule | | - | - | | `amount.amount` | The amount you sent, as a string, at least `1` with up to 2 decimals | | `amount.currency` | The currency you sent (`HKD` with `FPS`) | | `referenceId` | The exact Reference ID from step 1 | * **Confirming doesn't credit the funds.** It records the transfer as `PENDING` until Reap has verified it arrived. * **Keep the `id`.** It's the same `id` you'll see in your Treasury history. > [!TIP] > > **Why an `Idempotency-Key`?** Retry with the same key and body. A successfully stored response is replayed for 24 hours; changing the body with the same key is rejected. If Treasury records the confirmation before a timeout or 5xx prevents the response being stored, a retry can return `DUPLICATE_REFERENCE`. Reconcile Treasury history using the saved Reference ID before taking further action. Do not submit the same transfer under a new reference. Build the key from the Reference ID so it's naturally unique per transfer. **4. Check the funds landed** ```bash theme={"system"} curl "$REAP_API/treasury/transactions?product=CARD&type=DEPOSIT&from=2026-10-01" \ -H "x-api-key: $REAP_KEY" ``` ```json theme={"system"} { "items": [ { "id": "ttx_9Zx8Yv7Wu6Ts5Rq4Pn3Ml2Kj", "product": "CARD", "type": "DEPOSIT", "status": "PENDING", "direction": "CREDIT", "amount": { "amount": "100000.00", "currency": "HKD" }, "fee": null, "creditedAmount": null, "conversionRate": null, "method": { "type": "BANK_TRANSFER", "network": null }, "transactionHash": null, "referenceId": "IBM-ABCDEF", "createdAt": "2026-10-01T03:00:00.000Z", "completedAt": null } ], "meta": { "totalItems": 1, "itemCount": 1, "itemsPerPage": 20, "totalPages": 1, "currentPage": 1 } } ``` * **Find your transfer by `referenceId`** or by the `id` from the confirmation. * **It stays `PENDING` until Reap has reconciled the funds**, then becomes `COMPLETED`. * **Rejected bank transfers are removed from the history and never appear as `REJECTED` or `FAILED`.** A missing row alone doesn't prove rejection; check all pages and the date filters. `REJECTED`, `FAILED`, `REQUESTED`, `APPROVED`, `INVALID` and `NONE` can appear on other products (for example Optimize swaps) and are not accepted by the `status` filter, which takes `PENDING` or `COMPLETED` only. * **How long that takes depends on the Reference ID.** Reconciliation starts once the funds land in Reap's bank account; your bank's own transfer time comes on top (FPS is usually instant). With the Reference ID, the row turns `COMPLETED` within a few minutes of the funds landing. Without it, the Reap team reconciles the funds manually, which can take 1 to 2 business days. * **Poll every few minutes** for transfers sent with the Reference ID. If a transfer with the Reference ID is still `PENDING` or is no longer listed 30 minutes after the funds should have landed in Reap's bank account, contact Reap support with the Reference ID. **5. Check your card credit** Same as for stablecoins: call [`GET /cards/balances`](/api-reference/cards/retrieve-card-account-balances) and compare `totalCreditLimit` and `availableCredit` with the values from before the transfer. Once they've gone up, you can issue cards against the new funds. ## Following the rest of your Treasury history History queries use these rules: * A page can contain fewer items than `meta.itemsPerPage`. Follow `meta.totalPages` rather than stopping at a short page. * The `status` filter accepts only `PENDING` and `COMPLETED` and filters the underlying Treasury state. An Optimize swap can have a different displayed status. * Response status values also include `REQUESTED`, `APPROVED` and `NONE`; these are not supported status-filter values. The same endpoint shows every movement on your card collateral, not just funding. Filter with `type`: | `type` | What it is | | - | - | | `DEPOSIT` | Funds added to your card collateral | | `WITHDRAW` | Funds withdrawn | | `PAYMENT` | Payments from this balance | | `REPAYMENT` | Card balance repayments | | `ADJUSTMENT` | Corrections made by Reap, such as fees or waivers | Typical uses: syncing your card collateral movements into your accounting system each day, or reconciling them against your bank and exchange statements at month end. ## Common errors | Response | What it means | What to do | | - | - | - | | `400 FUNDING_METHOD_NOT_AVAILABLE` | This product, network or currency isn't available for your business | Use a method returned by funding options | | `400 DUPLICATE_REFERENCE` | This Reference ID is already confirmed | Check your Treasury history for it before doing anything else. Never resubmit under a new Reference ID | | `403 TREASURY_NOT_AVAILABLE` | Treasury isn't available for your business | Contact your Reap account manager | | `403 TREASURY_REQUESTER_NOT_AVAILABLE` | The person who created the API key is no longer an approved team member | Create a new key under a current team member | | `409 IDEMPOTENCY_KEY_IN_FLIGHT` | The first confirmation is still processing | Wait, then retry with the same key | | `422 IDEMPOTENCY_KEY_REUSED` | Same key sent with a different body | Use one key per transfer | | `429` | Too many requests | Wait, then retry | | `503 IDEMPOTENCY_UNAVAILABLE` | The outcome couldn't be verified; the confirmation may have completed | Check your Treasury history for the Reference ID, then retry with the same key | | `401` / `403` | Key or scope problem | Check the key and its scopes in the dashboard | Every error includes a `message` and often a `requestId`. Include the `requestId` when contacting Reap support. ## Go-live checklist * API key stored in a secrets manager, with only the scopes you need * Funding methods taken from funding options, never hard-coded * Crypto: funds sent only on the requested network, in a supported currency, above the minimum * Crypto: `IN_PROGRESS` handled by waiting `retryAfterSeconds` * Bank: one Reference ID per transfer, saved before sending * Bank: Reference ID in the transfer remarks (reconciled within a few minutes of the funds landing in Reap's bank account instead of the 1 to 2 business days manual matching can take), sent from an account in your business's name * Bank: transfer confirmed with an `Idempotency-Key` * Transfers matched in your Treasury history by transaction hash or Reference ID * Card crypto and bank transfers: contact support after 30 minutes if pending or missing; rejected transfers drop out of history * Optimize: stop polling when the returned status is `REJECTED` or `FAILED`, statuses that only appear on non-CARD products. See [Polling and waiting](/api-reference/polling.md) * Card balances checked before issuing cards against new funds This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.