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 walletOption two: your own walletOption three: you redeem yourself
Who receives the USDGthe user's deposit wallet at your provideryour own Robinhood Chain walletyour own wallet (it receives USDF)
What you send usreference, destination, deposit_idreference, destination (no deposit_id)nothing: no deposit address is used
How you match a useryour provider credits the user's deposit walletby reference and delivery_txentirely 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) and deposit_id (your provider's deposit id: the deposit's id, not the wallet's).
  • 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_id on every call for a deposit wallet. On an account set up for option one only, a call without it is refused (400 invalid_deposit_id) 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). A deposit_id can't be added to an address later: the same reference with a deposit_id answers 409 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_id: when the address is made, on a quote read with deposit_id, 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.

Option two: the address pays your own wallet.

  • Call with reference and destination (your own Robinhood Chain wallet), with no deposit_id. An account set up for option one only refuses this call (400 invalid_deposit_id); ask us which setups your account has.
  • You match each delivery to a user by its reference and delivery_tx (Reading state).
  • 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 to tells 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's from to 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 redeems amount of that wallet's own USDF and sends the same amount of USDG from the USDF contract to account, 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 as account. On chain, the USDG's sender is the USDF contract.
  • Where the USDG goes: to the account you 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.
ItemValue
ChainRobinhood Chain, chain ID 4663
Factory (DepositAddressFactory v1.1)0xe8dd4635f3Deb6137C8Dc2B0bbF34e2Bb77E5373
USDF0x4A35a5eC2A50A4d2957B2F2366E017f526cAB318 (6 decimals)
USDG0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168 (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).export({ type: "spki", format: "der" }).subarray(-32).toString("base64"); Python: base64.b64encode(key.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw))), or its PEM (BEGIN PUBLIC KEY) as openssl pkey -in partner.pem -pubout 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: send secp256k1:0x<your address> and sign with personal_sign (EIP-191).
  • 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_ip_refused; reads and release requests aren't checked. Without a list there is no IP check: your key and signature are enough.

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_id) 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 /v1/partners/deposit-addresses\n<raw body>. Sign the exact bytes you send. Each signed call is taken once; a retry gets a new timestamp and a new signature.

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 /v1/partners/deposit-addresses/0x<address>/flush\n (with no body, the last line is empty).

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 with 0x: 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_id it was first used with; sending a different deposit_id (or adding or dropping one) for that reference returns 409 deposit_id_mismatch.
  • Checking it yourself: the answer includes the derivation, so you can check the address against the factory's addressOf on 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_deposit_id: your provider doesn't know the id. 422 deposit_route_refused: 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.

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() and pushToFallback() are the fallback path (Wallet rotation, retiring an address, the fallback).

You can ask our keeper for a flush with POST /v1/partners/deposit-addresses/{address}/flush (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's withdrawTo are 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: delivered about 12 seconds after your deposit transaction; posted (to Ethereum) about 9 minutes 15 seconds after it; final about 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_at): 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; final (final_at, event deposit.final): Ethereum finality, about 6 minutes after posting, and it can no longer be reversed.
  • delivered can still be reverted by a chain reorg before posting. If that happens, the deposit goes back to received (event deposit.reverted, with reverted_tx), and our keeper delivers it again from what the address holds. A deposit whose own transaction disappears becomes reverted and 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_min_usd (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.
  • What to show your users: delivers.minimum in every address answer and minimum in GET /v1/partners/quote give your $3 minimum. They don't include your provider's route minimum, so for option one show the higher of the two. Each deposit.below_minimum event carries the exact minimum_units our keeper used.
  • 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 /v1/partners/deposit-addresses/{address}/release with {"deposit_ids": [...]} records your request and alerts us; it releases nothing by itself. If we clear the flag, our keeper delivers on its next pass.
  • 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 with pushToFallback().
  • 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 own arm() 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):

  1. Create a new address with the same deposit_id 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.
  2. Retire the old address at once: POST /v1/partners/deposit-addresses/{address}/retire (signed) with {"reason": "rotated", "note": "optional"}. The reasons are rotated, compromised, closed and other.
  3. 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_address_retired. For option one, a deposit wallet whose earlier address was retired gets no new address either: name the new wallet.
  • 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_id): 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.
  • 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.

CallWhat it reads
GET /v1/partners/deposit-addresses?reference=...Your addresses for one reference.
GET /v1/partners/deposit-addresses/{address}One address.
GET /v1/partners/deposits?status=&since=&limit=Your deposits, by status and time. Each carries its reference, and once delivered its delivery_tx (how option two matches a delivery to a user).
GET /v1/partners/deposits/{id}One deposit.
GET /v1/partners/quote?amount=...&deposit_id=...What an amount delivers.
StatusMeaning
screeningJust arrived, the senders being screened.
receivedCleared, waiting for delivery or for the minimum.
flaggedNot 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.
deliveredUSDG sent to the destination.
fallbackSent to your fallback wallet.
revertedThe deposit's own transaction is no longer on the chain (a reorg before posting); never delivered or counted.

under_review isn't a status: it's the review mark on a delivered deposit (and the deposit.under_review 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.under_review and deposit.fallback. Their data is 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.reverted adds reverted_tx. deposit.below_minimum adds address_open_units and minimum_units.
  • address.created and address.retired. Their data is the address: reference, address, chain_id, option, accepts, delivers; fallback_wallet, derivation, held; retired, retired_at, retire_reason, created_at.

Headers

  • x-usdf-event-id
  • x-usdf-timestamp
  • x-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"}}.

StatusCodeMeaning
400invalid_jsonThe body isn't JSON.
400invalid_requestAn unknown field.
400invalid_referenceThe reference isn't 1 to 64 letters, digits, - or _.
400invalid_destinationNot an address, or one of the refused destinations (Destination rules).
400invalid_deposit_idThe deposit id is malformed, or missing on an account set up for option one only; no address was made.
400unknown_deposit_idOption one: your provider knows no deposit with this id; no address was made.
400invalid_optionThe option isn't one you can use.
400invalid_reasonThe retire reason isn't one of rotated, compromised, closed, other.
400invalid_deposit_idsA release request needs 1 to 100 flagged deposit ids.
400invalid_amountThe quote amount isn't a whole number of base units from 1 to 10^15.
400invalid_status, invalid_since, invalid_limitA bad filter on the deposits read.
401unauthenticatedNo partner key, or not yours.
401registration_unsignedA missing, stale or wrong signature or timestamp.
401registration_replayedThat signature was already used.
403registration_not_set_upNo signing key on file for you.
403registration_ip_refusedThe call came from an address you didn't list (only if you gave us a list).
403option_not_set_upThat option isn't set up for you.
403address_refusedThe destination is refused by our screening.
404not_foundNo such address or deposit.
405method_not_allowedThe wrong method for that path.
409deposit_address_retiredThat address, or that deposit wallet's earlier address, was retired.
409deposit_id_mismatchThat reference is bound to the deposit_id it was first used with (or to none); send that one again, or use a new reference.
422deposit_route_refusedOption one: your provider refused the quote (deposit disabled, zero or several currencies, no settlement address, or no USDG route on Robinhood Chain).
422deposit_estimate_refusedOption one: your provider gives no estimate for this deposit id and amount.
422route_unavailableNo route for that option right now.
429rate_limitedMore than 600 calls a minute; see retry-after.
429deposit_addresses_day_capMore than 500 new addresses in 24 hours (ask us for more); see retry-after.
503deposits_unavailable, deposit_route_unavailable, deposit_estimate_unavailableRetry 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.

Foundry documentation

Confirm it's you

Confirm to continue the action you started.

Checking confirmation options…