Document the Core API v2 surface

[armandocodecr]

Adds a reference for the Core API v2 surface, which the skill did not cover at all. Everything here was read from the Core API source rather than from existing documentation.

Three new files under skills/api/v2/:

• core-concepts.md — base URL, auth, the build/sign/submit pattern, the shared roles / trustline / milestone shapes, type rules, field limits, and a v1→v2 comparison.
• single-release.md and multi-release.md — all 14 endpoints per variant, with an example payload, the required signer and the preconditions for each.

The existing V1 markers now point here, and SKILL.md routes to the new files.

Facts worth flagging to reviewers

Several of these contradict what a reader would assume from the V1 docs:

• V2 has its own host, https://beta.api.trustlesswork.com. Neither api.trustlesswork.com nor dev.api.trustlesswork.com serves it.
• The build response field is unsignedXdr, not unsignedTransaction, and it comes with txHash. deploy also returns the predicted contractId before you submit.
• Submission is POST /stellar/send-transaction. There is no helper controller in this API.
• Route names are not the controller file names: the endpoints are /deploy, /fund, /dispute, and update is PUT /update.
• milestoneIndexes is number[], where v1 used a single string milestoneIndex.
• Amount types are not symmetric: operate payloads take numbers, read responses return decimal strings.
• Milestones are optional at deploy in v2; v1 required at least one.
• Field limits changed: title 100→200, description 500→2000.
• trustline accepts either form — a contractId (C…) or symbol + issuer address (G…).
• STELLAR_TX_SUBMITTED_INDEXER_LAGGING on submit means the transaction succeeded and only the read model is behind. Retrying it is the most expensive mistake available.

Two read surfaces

Worth calling out because it is easy to get wrong: reads exist in two places. The v2 transaction controllers expose GET /escrow/{type}/v2/:contractId and /escrow-balances, while a separate read model serves /escrows/... with no version or type segment. Both SDKs use the second one. The document explains the split so nobody adds /v2/ to a read-model path.

Scope

Contract-level V2 semantics stay in skills/protocol/v2.md; this PR is the API layer only. The V2 React SDK and JS SDK are documented in a follow-up PR that builds on this one.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 4ceb9152-0d66-4e04-9e8b-f79f7d86cd99

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}