You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Document the dashboard route to API keys and an own-account ramp path - #1389
Integrator feedback showed two gaps in the API docs:
Authentication, Quick Start, and AI Agent Integration only described the programmatic OTP route to an API key. None of them mentioned the dashboard.
Integrators who ramp for their own account, such as a trading bot, had to work out from the managed-profile pages that they need no child profiles.
While checking the new text against the code, I found a stale claim in six places: bank-transfer buys (USD, MXN, COP, ARS) were said to receive their payment instructions (achPaymentData) in the POST /v1/ramp/start response. In fact the API returns them on the first POST /v1/ramp/update and on GET /v1/ramp/{id}, and the start response never carries them. The Quick Start example therefore printed undefined.
What
Authentication: a new section, "Get An API Key From The Dashboard". It covers production and sandbox dashboard URLs, email-code sign-in, API keys → Create credential, that the secret is shown once, and that existing customers must sign in with the email of their onboarded profile. Quick Start and AI Agent Integration link to it.
AI Agent Integration B.1, "Ramping On Your Own Account":
one-time setup in the dashboard: onboarding, payout account, API key;
the per-ramp sequence: quote → register → sign/update → fund → start → track;
the 15-minute start deadline;
why a bot may sign its own wallet transactions on its server.
Quick Start links to it.
achPaymentData timing: corrected in pages 02, 04, 09 and 12, in the SDK README, and in the vortex-integration skill. Buys now show the payment instructions, the user pays, and only then does the client call start, matching the widget.
Follow-up consistency fixes:
The OpenAPI SimpleStatus said COMPLETED, but every ramp response returns COMPLETE. It now has an enum and a note that COMPLETE and FAILED are terminal.
The vortex-integration skill's sell recipe called the removed listAlfredpayFiatAccounts, passed "MEX", and read accounts[0].id. It now uses listDomesticFiatAccounts("MX") and fiatAccountId. Its error class names are also updated to the current Domestic* names.
The SDK README no longer names the bank-transfer payment partner.
EUR availability, stated once: pages disagreed. Some said EUR buy works only for users provisioned out of band, with no SDK, Dashboard or Widget support. Others described a live SDK flow. The published @vortexfi/sdk@0.9.0 has no EUR support (only the removed Mykobo handler), and production activation is pending. Every page, the SDK README and the skill now say the same thing: sandbox now, production pending, SDK support in the next release.
Business EUR accounts: the /v1/monerium-b2b/* endpoints, the deposit events, and the Managed Profiles EU corridor text carry the same note: available in sandbox, production pending.
EUR provider naming: the docs text now says "EUR provider". Released API names (/v1/monerium* routes, MONERIUM_* codes, monerium* phases, Monerium* SDK errors) stay, and docs/api/README.md records them as deliberate exceptions.
Verification
bun run docs:api:check and bun run wire-contract:check pass. docs:api:types regenerated the .d.ts.
The SDK names used in the skill and README (listDomesticFiatAccounts, Domestic* errors) exist in the published @vortexfi/sdk@0.9.0.
Dashboard strings were checked against apps/dashboard: sign-in, the API keys page, the create dialog, and the Onboarding page's corridor and payout-account flows.
The sandbox dashboard bundle was checked to target api-sandbox.vortexfinance.co, which issues *_test_* keys.
The achPaymentData release path was checked in ramp.service.ts, where updateRamp calls startPersistedFlow and the start response omits the field. The SDK was checked too: registerRamp returns the update response for these buys. Staging and main behave the same.
Reviewer notes
The docs now publicly say EUR buy and the business EUR accounts are sandbox-only, with production activation pending.
https://dashboard-sandbox.vortexfinance.co is published in the docs for the first time.
After merge, re-import the changed pages into Apidog (manual step).
The API releases achPaymentData on the first ramp update and on status; the start response never carries it, so integrators following the docs read undefined.
Self-ramping integrators had to infer from managed-profile pages that they need no child profiles; spell out the setup and per-ramp sequence and link it from Quick Start.
SimpleStatus described COMPLETED, but every ramp response maps phases to TransactionStatus, which returns COMPLETE, so spec-following clients never detected completion.
The skill still called listAlfredpayFiatAccounts, which no longer exists, passed an alpha-3 country, and read a nonexistent id field, so its sell recipe could not run.
Pages disagreed on EUR: some described out-of-band provisioning with no SDK support, others a live SDK flow. The published SDK 0.9.0 has no EUR support and production is not yet activated, so every page now says sandbox now, production pending, SDK support in the next release. The same passages now say 'EUR provider' in prose while released routes, error codes and phase values keep their names, as recorded in the README exceptions.
The business EUR onramp account and its deposit events share the EUR provider activation that production is still waiting on, so they carry the same sandbox note as EUR buys.
This PR updates Vortex’s integration docs to help developers get API keys, ramp on their own account, and follow the correct bank-transfer and EUR flows.
Changes:
Add dashboard credential and own-account ramp guidance.
Correct bank-transfer payment-instruction timing and align EUR availability across guides.
Review found the own-account path sent EUR users to production keys, skipped EUR wallet linking and IBAN provisioning, omitted the country for the payout-account lookup, did not say direct clients sign the ephemeral transactions, and assumed verification creates the payout account.
Add and validate a payout account before accessing accounts[0]
.agents/skills/vortex-integration/SKILL.md:355
Listing payout accounts is not enough for a newly verified seller: verification does not create one, and the dashboard requires a separate Add pay-out account action (as the SDK README and Fiat Corridors guide now explain). If no account was added, listDomesticFiatAccounts returns an empty list and the recipe's accounts[0].fiatAccountId fails. Add that prerequisite, guard the empty list in the example, and correct the later claim that accounts are created during onboarding.
Use an MXN SELL quote for sell registration
.agents/skills/vortex-integration/SKILL.md:387
The corrected account lookup makes the MXN sell sample reach registerRamp(quote, ...), but the only quote above is for a BUY (or is undefined if the sell snippet is copied alone). The SDK dispatches that quote to the onramp handler, which requires destinationAddress, so this recipe cannot register a sell. Create an MXN SELL quote from USDC to SPEI and pass that quote here.
Select EUR customer type and sign with the returned permit signer
docs/api/pages/12-ai-agent-integration.md:46
The new own-account step gives walletAddress for both SDK and raw EUR registration, but the raw API selects the permit owner from the authenticated EUR provider binding, not this field. A client that relies on the supplied address could ask the wrong wallet to sign; if the account has both individual and business bindings, omitting customerType also produces 409 MONERIUM_CUSTOMER_TYPE_REQUIRED. Specify that walletAddress is for the SDK, select the legal type when needed, and sign the returned permit using its signer.
The API derives the EUR permit owner from the provider binding and ignores walletAddress, which only the SDK uses; accounts holding both legal types must also send customerType.
The sell example reused the buy quote, so registerRamp dispatched it to the onramp handler, and it indexed an empty account list for sellers who had not added a pay-out account.
The reason will be displayed to describe this comment to others. Learn more.
Copilot review overview
🔵 Needs a closer look
Public payment-sequencing and environment guidance needs final human validation, and two documentation corrections remain.
Review effort: Balanced Findings: None
Previously missed (2)
In code that hasn't changed since last review
Use DomesticCountry.MX instead of string literal in SDK examples
docs/api/pages/12-ai-agent-integration.md:46
The SDK parameter is the exported DomesticCountry enum, so TypeScript users cannot pass the string literal "MX" shown here; they get a type error before listing payout accounts. Use DomesticCountry.MX (imported from @vortexfi/sdk) in the SDK example, while keeping country=MX for HTTP. The new sell example in .agents/skills/vortex-integration/SKILL.md uses the same string and needs the same correction.
Document EUR sandbox-only availability for 0.9.0 users
packages/sdk/README.md:206
The README now directs 0.9.0 users to the direct API for EUR BUY, but does not say that EUR is available only in sandbox while production activation is pending. Someone following this page alone could try the production API with a live key. State the sandbox restriction next to the SDK-release requirement, as the Fiat Corridors guide does.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Integrator feedback showed two gaps in the API docs:
While checking the new text against the code, I found a stale claim in six places: bank-transfer buys (USD, MXN, COP, ARS) were said to receive their payment instructions (
achPaymentData) in thePOST /v1/ramp/startresponse. In fact the API returns them on the firstPOST /v1/ramp/updateand onGET /v1/ramp/{id}, and the start response never carries them. The Quick Start example therefore printedundefined.What
Authentication: a new section, "Get An API Key From The Dashboard". It covers production and sandbox dashboard URLs, email-code sign-in, API keys → Create credential, that the secret is shown once, and that existing customers must sign in with the email of their onboarded profile. Quick Start and AI Agent Integration link to it.
AI Agent Integration B.1, "Ramping On Your Own Account":
Quick Start links to it.
achPaymentDatatiming: corrected in pages 02, 04, 09 and 12, in the SDK README, and in thevortex-integrationskill. Buys now show the payment instructions, the user pays, and only then does the client call start, matching the widget.Follow-up consistency fixes:
SimpleStatussaidCOMPLETED, but every ramp response returnsCOMPLETE. It now has an enum and a note thatCOMPLETEandFAILEDare terminal.vortex-integrationskill's sell recipe called the removedlistAlfredpayFiatAccounts, passed"MEX", and readaccounts[0].id. It now useslistDomesticFiatAccounts("MX")andfiatAccountId. Its error class names are also updated to the currentDomestic*names.EUR availability, stated once: pages disagreed. Some said EUR buy works only for users provisioned out of band, with no SDK, Dashboard or Widget support. Others described a live SDK flow. The published
@vortexfi/sdk@0.9.0has no EUR support (only the removed Mykobo handler), and production activation is pending. Every page, the SDK README and the skill now say the same thing: sandbox now, production pending, SDK support in the next release.Business EUR accounts: the
/v1/monerium-b2b/*endpoints, the deposit events, and the Managed Profiles EU corridor text carry the same note: available in sandbox, production pending.EUR provider naming: the docs text now says "EUR provider". Released API names (
/v1/monerium*routes,MONERIUM_*codes,monerium*phases,Monerium*SDK errors) stay, anddocs/api/README.mdrecords them as deliberate exceptions.Verification
bun run docs:api:checkandbun run wire-contract:checkpass.docs:api:typesregenerated the.d.ts.listDomesticFiatAccounts,Domestic*errors) exist in the published@vortexfi/sdk@0.9.0.apps/dashboard: sign-in, the API keys page, the create dialog, and the Onboarding page's corridor and payout-account flows.api-sandbox.vortexfinance.co, which issues*_test_*keys.achPaymentDatarelease path was checked inramp.service.ts, whereupdateRampcallsstartPersistedFlowand the start response omits the field. The SDK was checked too:registerRampreturns the update response for these buys. Staging and main behave the same.Reviewer notes
The docs now publicly say EUR buy and the business EUR accounts are sandbox-only, with production activation pending.
https://dashboard-sandbox.vortexfinance.cois published in the docs for the first time.After merge, re-import the changed pages into Apidog (manual step).