Partners
Deposit addresses
Give each of your users a deposit address for USDF that delivers Global Dollar (USDG) 1:1 on Robinhood Chain, to their deposit wallet or to your own wallet, or redeem USDF yourself with no address at all.
On this page
Your users pay with USDF on Robinhood Chain, and what arrives is Global Dollar (USDG), 1:1. In options one and two each user gets their own deposit address from us, and the user's side is one send to that address, nothing else to sign. In option three no deposit address is used: your users send to a wallet of yours and your server redeems the USDF itself. Nothing is swapped or bridged, and the funds never sit in a Foundry wallet.
| Option one: deposit wallet | Option two: your own wallet | Option three: you redeem yourself | |
|---|---|---|---|
| Who receives the USDG | the user's deposit wallet at your provider | your own Robinhood Chain wallet | your own wallet (it receives USDF) |
| What you send us | reference, destination, deposit_ | reference, destination (no deposit_) | nothing: no deposit address is used |
| How you match a user | your provider credits the user's deposit wallet | by reference and delivery_ | entirely on your side |
Option one: the address pays the user's deposit wallet at your provider.
- Call with
reference,destination(the user's EVM deposit wallet on Robinhood Chain) anddeposit_(your provider's deposit id: the deposit's id, not the wallet's).id - Soft-confirmed deliveries: your deposit-wallet provider credits what arrives by its own confirmation rules. If it credits a delivery that a chain reorg later reverses, it may recover that from you, so check its rules.
- Send
deposit_on every call for a deposit wallet. On an account set up for option one only, a call without it is refused (400id invalid_) and no address is made. On any other account, an address made without it is handled as option two: no route check, no quote before delivery, no route minimum, and after a retire our keeper still delivers to the old wallet if you ask for a flush (Wallet rotation, retiring an address, the fallback). Adeposit_ id deposit_can't be added to an address later: the same reference with aid deposit_answers 409id deposit_.id_ mismatch - Your provider's activity calls: we never make them. Our only call to your provider is its swap quote for the
deposit_: when the address is made, on a quote read withid deposit_, and right before each delivery. If your provider asks you to record activity when you show a user an address, that call is yours, with your own provider credentials.id
Option two: the address pays your own wallet.
- Call with
referenceanddestination(your own Robinhood Chain wallet), with nodeposit_. An account set up for option one only refuses this call (400id invalid_); ask us which setups your account has.deposit_ id - You match each delivery to a user by its
referenceanddelivery_(Reading state).tx - Redeemed USDG arrives from the USDF contract, so the sender you see on chain is not the user.
Option three: your server redeems USDF itself (no deposit address, no keys from us).
- A wallet of yours: a Robinhood Chain wallet whose key your server holds, with a little ETH for gas. Your users send USDF to it, or to per-user wallets of it (next point).
- Telling users apart: a USDF transfer carries no memo, so either give each user a receiving wallet of their own, derived from your server's key (for example one HD path per user): the transfer's
totells you the user (each such wallet needs a little ETH to redeem, or first moves its USDF to your main wallet); or use one wallet and match each transfer'sfromto a sending wallet the user registered with you beforehand. - Redeeming: your server calls USDF
withdrawTo(account, amount)from the wallet that holds the USDF. It redeemsamountof that wallet's own USDF and sends the same amount of USDG from the USDF contract toaccount, 1:1, with no fee and no approval. There is no minimum, and gas is paid in ETH. Anyone holding USDF may call it; it refuses only the USDF contract itself asaccount. On chain, the USDG's sender is the USDF contract. - Where the USDG goes: to the
accountyou name: your own treasury wallet, or a wallet of your user's, and from there wherever your product sends it. - Not straight into a provider's deposit wallet: a deposit wallet credits only what its route takes (its minimum, one currency, its settlement address), and the provider holds an amount under its minimum until the wallet is topped up past it. Option one checks the route when the address is made and takes a fresh quote before every delivery; a redeem of your own skips both. For deposit wallets, use option one.
- Nothing from us: no API key, signing key or address is needed, and we don't screen, deliver or attribute anything here.
In options one and two (our deposit addresses):
- Anyone can trigger a delivery; nobody can redirect one. Anyone, you included, may call
flush()on an address. It only ever pays that address's fixed destination, or through the fallback path its fixed fallback wallet (Minimum, delivery and screening). - When to create addresses: when a user opens the deposit screen, not in bulk. The cap is 500 new addresses in any 24 hours (retired ones count; asking again for an address you already have doesn't). Ask us if you need more.
| Item | Value |
|---|---|
| Chain | Robinhood Chain, chain ID 4663 |
| Factory (DepositAddressFactory v1.1) | 0xe8dd4635f3Deb6137C8Dc2B0bbF34e2Bb77E5373 |
| USDF | 0x4A35a5eC2A50A4d2957B2F2366E017f526cAB318 (6 decimals) |
| USDG | 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168 (6 decimals) |
Amounts in the API are base units with 6 decimals (1000000 is 1).
- API key (
pfk_): send. . . Authorization: Bearer pfk_on every call. We keep only its SHA-256.. . . - Signing key (Ed25519): sign every create, retire and flush call with it (Make an address for a user). We check signatures with its public key only.
- Your own signing key instead of ours (recommended): make an Ed25519 key pair on your side, keep the private key, and send us only the public key, in either form:
ed25519:followed by the base64 of its raw 32 bytes (Node:createPublicKey(key).; Python:export({ type: "spki", format: "der" }). subarray(-32). toString("base64") base64.), or its PEM (b64encode(key. public_ key(). public_ bytes(Encoding. Raw, PublicFormat. Raw)) BEGIN PUBLIC KEY) asopenssl pkey -in partner.prints it. Send it to us (Get an API key); it's a public key, so any channel will do. We register it and confirm; from then on only your key's signatures are taken, and the key we generated is refused. You rotate your own key the same way: send us the new public key. A secp256k1 key works too: sendpem -pubout secp256k1:0x<your address>and sign withpersonal_(EIP-191).sign - What we generated for you: an API key and an Ed25519 signing key, handed over once by a one-time link. We delete our copy of the signing private key once you confirm you have it, and your API key is stored only as its SHA-256.
- Rotating them: ask us, at any time and at once if either may have leaked. We generate a new API key and signing key and send them, then switch your entry to the new key's hash and public key. From that moment the old ones are refused. Addresses you already created stay as they are; nothing on chain depends on your keys.
- Fallback wallet (optional): a Robinhood Chain wallet of yours that is written into each address when it is created, used only for funds that can't be delivered (Wallet rotation, retiring an address, the fallback). It must be set with us before your first address, and it can't be added to an address later.
- Webhook (optional): an https URL for our events (Webhooks). With it we give you a webhook secret (
whsec_, by one-time link). We sign every event with it, and you check each signature (Webhooks).. . . - IP allowlist (optional): up to 50 IP addresses or CIDR ranges (IPv4 /8 to /32, IPv6 /16 to /128) that your server calls from. With a list, a create, retire or flush call from anywhere else gets 403
registration_; reads and release requests aren't checked. Without a list there is no IP check: your key and signature are enough.ip_ refused
For option one, create the user's deposit wallet at your provider for USDG on Robinhood Chain first. Then pass that wallet address (destination) and its deposit id (deposit_) to our endpoint (Make an address for a user).
Never send USDF straight to a provider's deposit wallet. Send it only to the deposit address our endpoint returns.
Endpoint
POST https://api.usdf.fi/v1/partners/deposit-addresses
Authorization: Bearer pfk_. . . x-usdf-timestamp: <unix seconds>: within 300 seconds of our clock, either way.x-usdf-signature: ed25519=<base64 signature>over<timestamp>\nPOST /. Sign the exact bytes you send. Each signed call is taken once; a retry gets a new timestamp and a new signature.v1/ partners/ deposit-addresses\n<raw body>
Every signed call is signed the same way: over <timestamp>\n<METHOD> <path>\n<raw body>, with the path as you call it (no query string, no trailing slash) and the exact body bytes (none if you send no body). Create, retire and flush are signed:
- create:
<timestamp>\nPOST /;v1/ partners/ deposit-addresses\n{"reference":. . . } - retire:
<timestamp>\nPOST /;v1/ partners/ deposit-addresses/ 0x<address>/ retire\n{"reason":"rotated","note":". . . "} - flush:
<timestamp>\nPOST /(with no body, the last line is empty).v1/ partners/ deposit-addresses/ 0x<address>/ flush\n
Release requests and all reads need only your API key.
Body, option one
{"reference": "<your user id>", "destination": "<the user's deposit wallet>", "deposit_id": "<its deposit id>"}Body, option two
{"reference": "<your user id>", "destination": "<your own wallet>"}- The reference is 1 to 64 letters, digits,
-or_, not starting with0x: an opaque id, never an email. - Same answer twice: the same reference and destination always give the same address. Different references to one destination give different addresses.
- One deposit_id per reference: a reference is bound to the
deposit_it was first used with; sending a differentid deposit_(or adding or dropping one) for that reference returns 409id deposit_.id_ mismatch - Checking it yourself: the answer includes the derivation, so you can check the address against the factory's
addressOfon chain. - Route check (option one): before an address is made, we ask your provider to confirm the deposit id takes USDG on Robinhood Chain. 400
unknown_: your provider doesn't know the id. 422deposit_ id deposit_: your provider refused the quote (the deposit is disabled, it has zero or several currencies, no settlement address, or no USDG route on Robinhood Chain). Either way, no address is made.route_ refused
Node (18+)
import { createPrivateKey, sign } from "node:crypto";
import { readFileSync } from "node:fs";
const key = createPrivateKey(readFileSync("partner.pem", "utf8"));
const body = JSON.stringify({ reference: "user_123", destination: "0x...", deposit_id: "..." });
const ts = Math.floor(Date.now() / 1000);
const message = `${ts}\nPOST /v1/partners/deposit-addresses\n${body}`;
const signature = sign(null, Buffer.from(message), key).toString("base64");
const res = await fetch("https://api.usdf.fi/v1/partners/deposit-addresses", {
method: "POST",
headers: { authorization: `Bearer ${process.env.FOUNDRY_PARTNER_KEY}`, "content-type": "application/json", "x-usdf-timestamp": String(ts), "x-usdf-signature": `ed25519=${signature}` },
body,
});
console.log(res.status, await res.json());Python 3 (the cryptography package)
import base64, json, os, time, urllib.request from cryptography.hazmat.primitives.serialization import load_pem_private_key key = load_pem_private_key(open("partner.pem", "rb").read(), password=None) body = json.dumps({"reference": "user_123", "destination": "0x...", "deposit_id": "..."}) ts = str(int(time.time())) message = f"{ts}\nPOST /v1/partners/deposit-addresses\n{body}".encode() signature = base64.b64encode(key.sign(message)).decode() req = urllib.request.Request("https://api.usdf.fi/v1/partners/deposit-addresses", data=body.encode(), method="POST", headers={"Authorization": "Bearer " + os.environ["FOUNDRY_PARTNER_KEY"], "Content-Type": "application/json", "x-usdf-timestamp": ts, "x-usdf-signature": "ed25519=" + signature}) print(urllib.request.urlopen(req).read().decode())
Both examples were checked against our verifier: their signatures verify, and a changed body does not.
- What it can be: a normal wallet or a contract wallet on Robinhood Chain: the user's deposit wallet (option one) or your own wallet (option two).
- What our API refuses: the zero address, USDF, USDG, the factory, our own wallets and keeper, any deposit address, and a wallet frozen by its issuer. The address's contract itself refuses the zero address, USDF, USDG and the factory.
- Fixed at creation: the destination and the fallback wallet are written into the address's contract when it is created and can never change. No owner, admin, pause or rescue key exists, ours included.
Anyone can trigger a delivery; nobody can redirect one. The contract's flush(), sweep(token), arm() and pushToFallback() are open to anyone, and they only ever pay the address's fixed destination or its fixed fallback wallet:
flush()sends what the address holds to its fixed destination, with USDF redeemed 1:1 into USDG;sweep(token)sends any other token there;arm()andpushToFallback()are the fallback path (Wallet rotation, retiring an address, the fallback).
You can ask our keeper for a flush with POST / (signed). It queues a request for the keeper's next pass; it doesn't override a flag.
- Fees: none from us in options one and two.
flush()and USDF'swithdrawToare 1:1 and take nothing, and our keeper pays the gas. In option one, your provider's own fees are its own (they show in its quote). - Delivery time: our keeper checks every 5 seconds at the chain's latest head: the sequencer's soft confirmation, which Robinhood Chain gives in under a second. It screens a new deposit and, if it's above the minimum, delivers it in the same pass. What to expect, as measured on production:
deliveredabout 12 seconds after your deposit transaction;posted(to Ethereum) about 9 minutes 15 seconds after it;finalabout 15.5 minutes after it. - Credit your user on
final, about 16 minutes after their deposit. Each deposit carries three marks:delivered: the delivery has its sequencer receipt;posted(posted_): the batch holding the delivery is posted to Ethereum (the chain's safe head), and from then on it can only be reorganized if Ethereum itself is;at final(final_, eventat deposit.): Ethereum finality, about 6 minutes after posting, and it can no longer be reversed.final deliveredcan still be reverted by a chain reorg before posting. If that happens, the deposit goes back toreceived(eventdeposit., withreverted reverted_), and our keeper delivers it again from what the address holds. A deposit whose own transaction disappears becomestx revertedand is never delivered.
Our keeper's rules: the minimum, the quote check and screening are rules our keeper follows before it flushes; the contract doesn't enforce them.
- Minimum: our keeper delivers at your minimum, $3. For option one it uses the highest of $3, your
route_(set to your provider's route minimum for you) and the fresh quote's minimum. Smaller amounts wait in the address until they add up.min_ usd - What to show your users:
delivers.in every address answer andminimum minimuminGET /give your $3 minimum. They don't include your provider's route minimum, so for option one show the higher of the two. Eachv1/ partners/ quote deposit.event carries the exactbelow_ minimum minimum_our keeper used.units - Quote check (option one): right before each delivery our keeper asks your provider for a fresh quote. If your provider refuses or errors, our keeper doesn't deliver on that pass, we're alerted, and it asks again on later passes.
- Screening binds our keeper only. Our keeper screens every deposit's senders before it delivers. Our keeper doesn't deliver a flagged deposit, and while it's flagged it doesn't move, arm or push that address. The contract knows nothing of this: anyone's
flush()still delivers the funds to the destination, and a due fallback push still sends them to the fallback wallet. So screen what arrives at your destination too. - Asking us to look again:
POST /withv1/ partners/ deposit-addresses/ {address}/ release {"deposit_records your request and alerts us; it releases nothing by itself. If we clear the flag, our keeper delivers on its next pass.ids": [. . . ]} - Dust flushed by someone else (option one): because anyone can call
flush(), a third party can deliver an amount below the minimum to the deposit wallet. Your provider holds such an arrival until the wallet is topped up past its minimum. - Dust that never adds up: with a fallback wallet, an amount below the minimum can be armed by anyone with
arm()and pushed to your fallback wallet 7 days later withpushToFallback(). arm()in detail: it arms everything the address holds that isn't already armed, on a 7-day clock. With nothing new since the last arm it reverts (NothingToArm), and without a fallback wallet it always reverts. Funds that arrive after an arm need their ownarm()and their own 7 days; once something is armed, a new arm must be at least 3 USDG. A flush uses up armed amounts oldest first, by what it moves. An address holds up to 32 armed amounts.- Paused or frozen by its issuer: if USDG is paused by its issuer, or the destination is frozen for USDG,
flush()reverts and nothing moves; our keeper tries again until it isn't.
When your provider rotates a user's deposit wallet (option one):
- Create a new address with the same
deposit_and the user's new wallet as the destination (Make an address for a user). The deposit id doesn't change; only the wallet does.id - Retire the old address at once:
POST /(signed) withv1/ partners/ deposit-addresses/ {address}/ retire {"reason": "rotated", "note": "optional"}. The reasons arerotated,compromised,closedandother. - Show the user only the new address.
What a retired address does:
- Marked retired: our reads show it as retired, and it's never given out again; asking for the same reference and destination answers 409
deposit_. For option one, a deposit wallet whose earlier address was retired gets no new address either: name the new wallet.address_ retired - Retire stops our keeper, not the contract. The contract has no retire: anyone can still call
flush(), which sends to the address's fixed destination. - Option one (with
deposit_): our keeper never sends to the old wallet again, and a flush request answers 409. With a fallback wallet, our keeper arms late funds (at most once an hour) and they go to the fallback 7 days later.id - Option two: our keeper leaves a retired address alone unless you ask for a flush, which then delivers to its destination.
- Funds sent there later: with a fallback wallet they can go to it 7 days after arming; without one they wait in the address. Either way, anyone's
flush()still sends them to the old destination first.
What a fallback wallet is for: recovering late funds sent to an address whose destination you've closed, such as a rotated deposit wallet. It doesn't protect a compromised destination: anyone can still flush to it. For a compromised destination, make a new address and retire the old one as compromised.
| Call | What it reads |
|---|---|
GET / | Your addresses for one reference. |
GET / | One address. |
GET / | Your deposits, by status and time. Each carries its reference, and once delivered its delivery_ (how option two matches a delivery to a user). |
GET / | One deposit. |
GET / | What an amount delivers. |
| Status | Meaning |
|---|---|
screening | Just arrived, the senders being screened. |
received | Cleared, waiting for delivery or for the minimum. |
flagged | Not delivered by our keeper (Minimum, delivery and screening). It ends as delivered (we clear the flag and our keeper delivers it, or anyone calls flush()) or as fallback (a due fallback push). There is no refund to the sender. |
delivered | USDG sent to the destination. |
fallback | Sent to your fallback wallet. |
reverted | The deposit's own transaction is no longer on the chain (a reorg before posting); never delivered or counted. |
under_ isn't a status: it's the review mark on a delivered deposit (and the deposit. event) when a delivery's amounts differ from what we recorded. The money has reached the destination; we look into the difference and tell you.
Each event is one POST with this body:
Event
{"id": "evt_...", "type": "deposit.delivered", "created_at": "...", "data": { ... }}Events
deposit.,received deposit.,received_ on_ retired deposit.,flagged deposit.,below_ minimum deposit.,delivered deposit.,final deposit.,reverted deposit.andunder_ review deposit.. Theirfallback datais the deposit:id,reference,deposit_,address option,destination,chain_;id asset_,in amount_,in_ units from,sender,deposit_,tx block;status,review,screened,released,address_,retired on_;retired flush_,tx delivery_,tx fallback_,tx failure,explorer;delivered_,at posted,posted_,at final,final_,at created_,at updated_;at deposit.addsreverted reverted_.tx deposit.addsbelow_ minimum address_andopen_ units minimum_.units address.andcreated address.. Theirretired datais the address:reference,address,chain_,id option,accepts,delivers;fallback_,wallet derivation,held;retired,retired_,at retire_,reason created_.at
Headers
x-usdf-event-idx-usdf-timestampx-usdf-destination: the URL the event was sent to.x-usdf-signature: v1=<hex HMAC-SHA256>, keyed by the webhook secret we give you, over<timestamp>\n<URL>\n<raw body>. Refuse a timestamp more than 300 seconds from your clock.
Retries: each POST waits 10 seconds for a 2xx. Otherwise it's retried after 20 s, 40 s, 80 s and so on, up to every 15 minutes, for 24 hours.
Every error is JSON {"error": {"message", "type", "code", "param"}}.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_ | The body isn't JSON. |
| 400 | invalid_ | An unknown field. |
| 400 | invalid_ | The reference isn't 1 to 64 letters, digits, - or _. |
| 400 | invalid_ | Not an address, or one of the refused destinations (Destination rules). |
| 400 | invalid_ | The deposit id is malformed, or missing on an account set up for option one only; no address was made. |
| 400 | unknown_ | Option one: your provider knows no deposit with this id; no address was made. |
| 400 | invalid_ | The option isn't one you can use. |
| 400 | invalid_ | The retire reason isn't one of rotated, compromised, closed, other. |
| 400 | invalid_ | A release request needs 1 to 100 flagged deposit ids. |
| 400 | invalid_ | The quote amount isn't a whole number of base units from 1 to 10^15. |
| 400 | invalid_ | A bad filter on the deposits read. |
| 401 | unauthenticated | No partner key, or not yours. |
| 401 | registration_ | A missing, stale or wrong signature or timestamp. |
| 401 | registration_ | That signature was already used. |
| 403 | registration_ | No signing key on file for you. |
| 403 | registration_ | The call came from an address you didn't list (only if you gave us a list). |
| 403 | option_ | That option isn't set up for you. |
| 403 | address_ | The destination is refused by our screening. |
| 404 | not_ | No such address or deposit. |
| 405 | method_ | The wrong method for that path. |
| 409 | deposit_ | That address, or that deposit wallet's earlier address, was retired. |
| 409 | deposit_ | That reference is bound to the deposit_id it was first used with (or to none); send that one again, or use a new reference. |
| 422 | deposit_ | Option one: your provider refused the quote (deposit disabled, zero or several currencies, no settlement address, or no USDG route on Robinhood Chain). |
| 422 | deposit_ | Option one: your provider gives no estimate for this deposit id and amount. |
| 422 | route_ | No route for that option right now. |
| 429 | rate_ | More than 600 calls a minute; see retry-after. |
| 429 | deposit_ | More than 500 new addresses in 24 hours (ask us for more); see retry-after. |
| 503 | deposits_ | Retry shortly (a 503 also answers while a destination is still being screened). |
Need an API key? Email protocol@usdf.fi and we'll set up your partner account.