FAQ

Getting started

Do I need to talk to someone before I can build? Only to receive your invitation. Accept it, sign in at the dashboard, set up your company, and create an sk_test_ key: the sandbox is open from then on. Live access needs your executed Partner Terms on record, your own business verification approved, and your live wallet keys registered and activated, all tracked on the dashboard's onboarding checklist. Start that early: it gates launch and does not depend on your code.

How close is the sandbox to live? It has the same endpoints, objects, statuses, and error envelopes, and it delivers real signed webhooks. Verification decisions, bank deposits, and treasury funding are simulated, and wallets run on testnet. Sandbox Testing lists every difference.

How much code changes when I go live? The base URL and the key. Endpoints and shapes are identical.

Are there SDKs? Not yet. The API is plain REST with JSON. The OpenAPI spec behind the API Reference is generated from the application's own schema, and you can generate a client from it. Check generated code against these pages for the rules a schema cannot express, such as sending amounts as strings.

Customers and verification

Why does verification need a separate submit call? Documents sent on create or PATCH are held, not reviewed, until the first submit. That lets you collect identity material over several screens without starting a review each time, and it makes submitting a decision your code makes rather than a side effect of an upload. After the first submission, a PATCH that changes something resubmits by itself.

Do I have to send my customer's name, date of birth, and address? No, for an individual or a business. At submit we read the identity document and proof of address, and for a business its registration document and each controller's documents, then fill the fields you left empty. A value you send is never overwritten, and only what the documents could not supply is asked.

Which documents do I need to collect? An individual owes an identity document and a selfie, plus a proof of address when they live outside the US. A business owes the documents its legal form needs, such as articles of association, an operating agreement, ownership information, or a list of authorized signatories, and an identity document and proof of address for each controller. Once you request an endorsement, its missing bucket lists every document still owed. The full table is in Documents we ask for.

What is an endorsement, and why not just read verification_status? The endorsement is the review of the customer for one currency, and that review is the verification. It answers the question you actually have, which is "can this customer use USD services yet". Verification status is internal, and there are no verification.* webhooks.

Why did requesting endo_usd fail with a 422? For an individual it requires email and phone, already on the customer or in the same request. For a business it requires email. The response names what is missing. This is enforced in sandbox too, on purpose, so the contract is learned before go-live.

Do I need tax data to request endo_usd? No, but the review needs it. Send tax_id, and tax_residence_country for an individual, on create. In live, until they arrive, the endorsement lists them in missing and the submit returns 422 verification_incomplete.

A customer was approved, and now the endorsement reads issues. Why? The review's word stands in both directions, so it can ask for more after approving. Anything that needs the endorsement approved, such as creating a virtual account, is refused until it is approved again. Supply what the buckets list with a PATCH, which resubmits by itself.

I added a document after approval. Was it reviewed? No. It is held in uploaded, and the approval stands.

Money movement

Where do fees show up? Itemized on the conversion's fee_lines, each carrying a collection of realtime or monthly. Realtime lines were netted from the delivery. Monthly lines are metering for your invoice and did not reduce it.

Why is my deposit stuck in orchestrating? Almost always treasury inventory. In sandbox, fund it first with POST /api/sandbox/treasury/deposits. In live, the delivery waits and proceeds as soon as inventory is replenished.

What is the difference between failed and returned? failed means nothing moved, so a retry is safe. returned means money moved and came back, so reconcile before re-sending.

Can one customer have two USD accounts? No. One account receives over every USD rail, so a second create returns 400 virtual_account_exists. PATCH the existing account's destination instead.

Wallets

Can you move funds for me if I lose access to my signing service? No. We hold no key that can move your customers' funds, and there is no escrow or break-glass path.

Can I rotate my Primary Signing Key? Yes, freely. Your Recovery Key installs the replacement, and addresses never change, because they derive from the Recovery Key rather than the Primary Signing Key.

Can I rotate my Recovery Key? No. It is the identity every address derives from. Generate it offline and back it up accordingly.

Why is the authorization window only 30 seconds? It pins live chain state. On Solana a finalized blockhash is already about 35 slots old when we read it, leaving roughly 46 seconds of its life, and the message cannot be rebuilt once your key has signed it. Verify and sign automatically, and put human approval before the operation is created.

Do I really have to run the verifier? Yes. It exists to be correct when we are compromised. Signing an unverified authorization gives up the exact property non-custodial wallets provide.

Platform

How do I know a webhook came from you? Verify the signature against the raw request body before parsing it, and reject stale timestamps. See Verifying signatures.

I missed some webhooks. Are they gone? No. GET /api/webhook_events lists everything we emitted, delivered or not, and you can replay individual events. See Reconciliation.

Something went wrong and the message is vague. What do I send support? The request-id from the response header. It finds the exact request, including the original wording of any downstream failure, which never reaches the API response by design.

Will you break my integration? Additive changes ship without notice, so ignore unknown fields and tolerate unfamiliar enum values. Breaking changes arrive under a new Api-Version date, announced in the Changelog, and omitting the header pins you to the oldest supported version.