diff --git a/AGENTS.md b/AGENTS.md index 2e882dac..4bb9035e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,10 +12,7 @@ | Repo | Type | Spec | |------|------|------| -| `sprintertech/miso-api` | REST API (Go/Gin) | OpenAPI 3.0 at `api-reference/miso/openapi.json` | | `sprintertech/sprinter-api` | REST API (Go/Gin) | OpenAPI 3.0 at `api-reference/sprinter/openapi.json` | -| `sprintertech/sprinter-signing` | MPC signing (Go/Gorilla Mux) | Manual MDX pages in `api-reference/signing/` | -| `sprintertech/stash-repayment` | Background worker (Go) | Architecture page in `architecture/` | ## Terminology diff --git a/api-reference/miso/health-check.mdx b/api-reference/miso/health-check.mdx deleted file mode 100644 index 12da679a..00000000 --- a/api-reference/miso/health-check.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "Miso API - Health Check" -sidebarTitle: "Health Check" -openapi: get /health ---- - - -```bash cURL -curl --request GET \ - --url 'https://api.getmiso.fi/health' -``` - -```python Python -import requests - -response = requests.get("https://api.getmiso.fi/health") -print(response.json()) -``` - -```javascript JavaScript -const response = await fetch( - "https://api.getmiso.fi/health" -); -const data = await response.json(); -console.log(data); -``` - -```go Go -package main - -import ( - "fmt" - "io" - "net/http" -) - -func main() { - resp, _ := http.Get("https://api.getmiso.fi/health") - defer resp.Body.Close() - body, _ := io.ReadAll(resp.Body) - fmt.Println(string(body)) -} -``` - \ No newline at end of file diff --git a/api-reference/miso/miso/check-username-availability.mdx b/api-reference/miso/miso/check-username-availability.mdx deleted file mode 100644 index 83aeea76..00000000 --- a/api-reference/miso/miso/check-username-availability.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Miso API - Check Username Availability" -sidebarTitle: "Check Username Availability" -openapi: post /miso/username/check ---- - - -```bash cURL -curl --request POST \ - --url 'https://api.getmiso.fi/miso/username/check' \ - -H 'Content-Type: application/json' \ - -d '{}' -``` - -```python Python -import requests - -response = requests.post( - "https://api.getmiso.fi/miso/username/check", - json={} -) -print(response.json()) -``` - -```javascript JavaScript -const response = await fetch( - "https://api.getmiso.fi/miso/username/check", - { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({}), - } -); -const data = await response.json(); -console.log(data); -``` - -```go Go -package main - -import ( - "bytes" - "fmt" - "io" - "net/http" -) - -func main() { - resp, _ := http.NewRequest("POST", "https://api.getmiso.fi/miso/username/check", bytes.NewBuffer([]byte("{}"))) - resp.Header.Set("Content-Type", "application/json") - client := &http.Client{} - res, _ := client.Do(resp) - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - fmt.Println(string(body)) -} -``` - \ No newline at end of file diff --git a/api-reference/miso/miso/complete-tuyo-oauth-flow.mdx b/api-reference/miso/miso/complete-tuyo-oauth-flow.mdx deleted file mode 100644 index 2bbcf0da..00000000 --- a/api-reference/miso/miso/complete-tuyo-oauth-flow.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Miso API - Complete Tuyo OAuth Flow" -sidebarTitle: "Complete Tuyo OAuth Flow" -openapi: post /miso/cards/tuyo/authorize ---- - - -```bash cURL -curl --request POST \ - --url 'https://api.getmiso.fi/miso/cards/tuyo/authorize' \ - -H 'Content-Type: application/json' \ - -d '{}' -``` - -```python Python -import requests - -response = requests.post( - "https://api.getmiso.fi/miso/cards/tuyo/authorize", - json={} -) -print(response.json()) -``` - -```javascript JavaScript -const response = await fetch( - "https://api.getmiso.fi/miso/cards/tuyo/authorize", - { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({}), - } -); -const data = await response.json(); -console.log(data); -``` - -```go Go -package main - -import ( - "bytes" - "fmt" - "io" - "net/http" -) - -func main() { - resp, _ := http.NewRequest("POST", "https://api.getmiso.fi/miso/cards/tuyo/authorize", bytes.NewBuffer([]byte("{}"))) - resp.Header.Set("Content-Type", "application/json") - client := &http.Client{} - res, _ := client.Do(resp) - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - fmt.Println(string(body)) -} -``` - \ No newline at end of file diff --git a/api-reference/miso/miso/create-a-new-card.mdx b/api-reference/miso/miso/create-a-new-card.mdx deleted file mode 100644 index 51455227..00000000 --- a/api-reference/miso/miso/create-a-new-card.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Miso API - Create a New Card" -sidebarTitle: "Create a New Card" -openapi: post /miso/cards ---- - - -```bash cURL -curl --request POST \ - --url 'https://api.getmiso.fi/miso/cards' \ - -H 'Content-Type: application/json' \ - -d '{}' -``` - -```python Python -import requests - -response = requests.post( - "https://api.getmiso.fi/miso/cards", - json={} -) -print(response.json()) -``` - -```javascript JavaScript -const response = await fetch( - "https://api.getmiso.fi/miso/cards", - { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({}), - } -); -const data = await response.json(); -console.log(data); -``` - -```go Go -package main - -import ( - "bytes" - "fmt" - "io" - "net/http" -) - -func main() { - resp, _ := http.NewRequest("POST", "https://api.getmiso.fi/miso/cards", bytes.NewBuffer([]byte("{}"))) - resp.Header.Set("Content-Type", "application/json") - client := &http.Client{} - res, _ := client.Do(resp) - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - fmt.Println(string(body)) -} -``` - \ No newline at end of file diff --git a/api-reference/miso/miso/delete-a-card.mdx b/api-reference/miso/miso/delete-a-card.mdx deleted file mode 100644 index 80371635..00000000 --- a/api-reference/miso/miso/delete-a-card.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Miso API - Delete a Card" -sidebarTitle: "Delete a Card" -openapi: delete /miso/cards/{cardId} ---- - - -```bash cURL -curl --request DELETE \ - --url 'https://api.getmiso.fi/miso/cards/{cardId}' \ - -H 'Content-Type: application/json' \ - -d '{}' -``` - -```python Python -import requests - -response = requests.delete( - "https://api.getmiso.fi/miso/cards/{cardId}", - json={} -) -print(response.json()) -``` - -```javascript JavaScript -const response = await fetch( - "https://api.getmiso.fi/miso/cards/{cardId}", - { - method: "DELETE", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({}), - } -); -const data = await response.json(); -console.log(data); -``` - -```go Go -package main - -import ( - "bytes" - "fmt" - "io" - "net/http" -) - -func main() { - resp, _ := http.NewRequest("DELETE", "https://api.getmiso.fi/miso/cards/{cardId}", bytes.NewBuffer([]byte("{}"))) - resp.Header.Set("Content-Type", "application/json") - client := &http.Client{} - res, _ := client.Do(resp) - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - fmt.Println(string(body)) -} -``` - \ No newline at end of file diff --git a/api-reference/miso/miso/get-user-cards.mdx b/api-reference/miso/miso/get-user-cards.mdx deleted file mode 100644 index 496a31a0..00000000 --- a/api-reference/miso/miso/get-user-cards.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "Miso API - Get User Cards" -sidebarTitle: "Get User Cards" -openapi: get /miso/cards ---- - - -```bash cURL -curl --request GET \ - --url 'https://api.getmiso.fi/miso/cards' -``` - -```python Python -import requests - -response = requests.get("https://api.getmiso.fi/miso/cards") -print(response.json()) -``` - -```javascript JavaScript -const response = await fetch( - "https://api.getmiso.fi/miso/cards" -); -const data = await response.json(); -console.log(data); -``` - -```go Go -package main - -import ( - "fmt" - "io" - "net/http" -) - -func main() { - resp, _ := http.Get("https://api.getmiso.fi/miso/cards") - defer resp.Body.Close() - body, _ := io.ReadAll(resp.Body) - fmt.Println(string(body)) -} -``` - \ No newline at end of file diff --git a/api-reference/miso/miso/get-user-profile.mdx b/api-reference/miso/miso/get-user-profile.mdx deleted file mode 100644 index 6db2c536..00000000 --- a/api-reference/miso/miso/get-user-profile.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "Miso API - Get User Profile" -sidebarTitle: "Get User Profile" -openapi: get /miso/user ---- - - -```bash cURL -curl --request GET \ - --url 'https://api.getmiso.fi/miso/user' -``` - -```python Python -import requests - -response = requests.get("https://api.getmiso.fi/miso/user") -print(response.json()) -``` - -```javascript JavaScript -const response = await fetch( - "https://api.getmiso.fi/miso/user" -); -const data = await response.json(); -console.log(data); -``` - -```go Go -package main - -import ( - "fmt" - "io" - "net/http" -) - -func main() { - resp, _ := http.Get("https://api.getmiso.fi/miso/user") - defer resp.Body.Close() - body, _ := io.ReadAll(resp.Body) - fmt.Println(string(body)) -} -``` - \ No newline at end of file diff --git a/api-reference/miso/miso/initiate-tuyo-oauth-flow.mdx b/api-reference/miso/miso/initiate-tuyo-oauth-flow.mdx deleted file mode 100644 index 5ea27ac8..00000000 --- a/api-reference/miso/miso/initiate-tuyo-oauth-flow.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Miso API - Initiate Tuyo OAuth Flow" -sidebarTitle: "Initiate Tuyo OAuth Flow" -openapi: post /miso/cards/tuyo/create ---- - - -```bash cURL -curl --request POST \ - --url 'https://api.getmiso.fi/miso/cards/tuyo/create' \ - -H 'Content-Type: application/json' \ - -d '{}' -``` - -```python Python -import requests - -response = requests.post( - "https://api.getmiso.fi/miso/cards/tuyo/create", - json={} -) -print(response.json()) -``` - -```javascript JavaScript -const response = await fetch( - "https://api.getmiso.fi/miso/cards/tuyo/create", - { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({}), - } -); -const data = await response.json(); -console.log(data); -``` - -```go Go -package main - -import ( - "bytes" - "fmt" - "io" - "net/http" -) - -func main() { - resp, _ := http.NewRequest("POST", "https://api.getmiso.fi/miso/cards/tuyo/create", bytes.NewBuffer([]byte("{}"))) - resp.Header.Set("Content-Type", "application/json") - client := &http.Client{} - res, _ := client.Do(resp) - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - fmt.Println(string(body)) -} -``` - \ No newline at end of file diff --git a/api-reference/miso/miso/register-a-new-user.mdx b/api-reference/miso/miso/register-a-new-user.mdx deleted file mode 100644 index 2bdaef5f..00000000 --- a/api-reference/miso/miso/register-a-new-user.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Miso API - Register a New User" -sidebarTitle: "Register a New User" -openapi: post /miso/register ---- - - -```bash cURL -curl --request POST \ - --url 'https://api.getmiso.fi/miso/register' \ - -H 'Content-Type: application/json' \ - -d '{}' -``` - -```python Python -import requests - -response = requests.post( - "https://api.getmiso.fi/miso/register", - json={} -) -print(response.json()) -``` - -```javascript JavaScript -const response = await fetch( - "https://api.getmiso.fi/miso/register", - { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({}), - } -); -const data = await response.json(); -console.log(data); -``` - -```go Go -package main - -import ( - "bytes" - "fmt" - "io" - "net/http" -) - -func main() { - resp, _ := http.NewRequest("POST", "https://api.getmiso.fi/miso/register", bytes.NewBuffer([]byte("{}"))) - resp.Header.Set("Content-Type", "application/json") - client := &http.Client{} - res, _ := client.Do(resp) - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - fmt.Println(string(body)) -} -``` - \ No newline at end of file diff --git a/api-reference/miso/miso/rename-a-card.mdx b/api-reference/miso/miso/rename-a-card.mdx deleted file mode 100644 index 35a41b8d..00000000 --- a/api-reference/miso/miso/rename-a-card.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Miso API - Rename a Card" -sidebarTitle: "Rename a Card" -openapi: patch /miso/cards/{cardId} ---- - - -```bash cURL -curl --request PATCH \ - --url 'https://api.getmiso.fi/miso/cards/{cardId}' \ - -H 'Content-Type: application/json' \ - -d '{}' -``` - -```python Python -import requests - -response = requests.patch( - "https://api.getmiso.fi/miso/cards/{cardId}", - json={} -) -print(response.json()) -``` - -```javascript JavaScript -const response = await fetch( - "https://api.getmiso.fi/miso/cards/{cardId}", - { - method: "PATCH", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({}), - } -); -const data = await response.json(); -console.log(data); -``` - -```go Go -package main - -import ( - "bytes" - "fmt" - "io" - "net/http" -) - -func main() { - resp, _ := http.NewRequest("PATCH", "https://api.getmiso.fi/miso/cards/{cardId}", bytes.NewBuffer([]byte("{}"))) - resp.Header.Set("Content-Type", "application/json") - client := &http.Client{} - res, _ := client.Do(resp) - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - fmt.Println(string(body)) -} -``` - \ No newline at end of file diff --git a/api-reference/miso/miso/validate-referral-code.mdx b/api-reference/miso/miso/validate-referral-code.mdx deleted file mode 100644 index cc11f506..00000000 --- a/api-reference/miso/miso/validate-referral-code.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Miso API - Validate Referral Code" -sidebarTitle: "Validate Referral Code" -openapi: post /miso/referral/validate ---- - - -```bash cURL -curl --request POST \ - --url 'https://api.getmiso.fi/miso/referral/validate' \ - -H 'Content-Type: application/json' \ - -d '{}' -``` - -```python Python -import requests - -response = requests.post( - "https://api.getmiso.fi/miso/referral/validate", - json={} -) -print(response.json()) -``` - -```javascript JavaScript -const response = await fetch( - "https://api.getmiso.fi/miso/referral/validate", - { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({}), - } -); -const data = await response.json(); -console.log(data); -``` - -```go Go -package main - -import ( - "bytes" - "fmt" - "io" - "net/http" -) - -func main() { - resp, _ := http.NewRequest("POST", "https://api.getmiso.fi/miso/referral/validate", bytes.NewBuffer([]byte("{}"))) - resp.Header.Set("Content-Type", "application/json") - client := &http.Client{} - res, _ := client.Do(resp) - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - fmt.Println(string(body)) -} -``` - \ No newline at end of file diff --git a/api-reference/miso/openapi-v2.json b/api-reference/miso/openapi-v2.json deleted file mode 100644 index abdc6f16..00000000 --- a/api-reference/miso/openapi-v2.json +++ /dev/null @@ -1,1071 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "contact": {} - }, - "paths": { - "/health": { - "get": { - "description": "health check", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "summary": "health check", - "responses": { - "200": { - "description": "OK", - "schema": { - "$ref": "#/definitions/server.HealthHandler.response" - } - } - } - } - }, - "/miso/cards": { - "get": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Returns all cards for the authenticated user", - "produces": [ - "application/json" - ], - "tags": [ - "Miso" - ], - "summary": "Get user cards", - "responses": { - "200": { - "description": "List of user's cards", - "schema": { - "$ref": "#/definitions/cards.CardsResponse" - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "404": { - "description": "User not found", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - }, - "post": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Creates a new card for the authenticated user", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Miso" - ], - "summary": "Create a new card", - "parameters": [ - { - "description": "Card details", - "name": "request", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/cards.CreateCardRequest" - } - } - ], - "responses": { - "201": { - "description": "Card created successfully", - "schema": { - "$ref": "#/definitions/cards.CardResponse" - } - }, - "400": { - "description": "Invalid request body or validation error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "404": { - "description": "User not found", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "409": { - "description": "Card already exists", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/miso/cards/tuyo/authorize": { - "post": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Validates the OAuth state, exchanges the authorization code for tokens, and creates a Tuyo card or re-authenticates an existing one.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Miso" - ], - "summary": "Complete Tuyo OAuth flow", - "parameters": [ - { - "description": "OAuth callback parameters", - "name": "request", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/cards.TuyoCallbackRequest" - } - } - ], - "responses": { - "200": { - "description": "Re-authentication successful", - "schema": { - "$ref": "#/definitions/cards.CardResponse" - } - }, - "201": { - "description": "Card created successfully", - "schema": { - "$ref": "#/definitions/cards.CardResponse" - } - }, - "400": { - "description": "Invalid request, state, or authorization code", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "404": { - "description": "User not found", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "409": { - "description": "Tuyo account already connected", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "502": { - "description": "Tuyo service unavailable", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/miso/cards/tuyo/create": { - "post": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Generates an OAuth state and returns the Tuyo authorization URL. If cardId is provided, initiates re-authentication for an existing card.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Miso" - ], - "summary": "Initiate Tuyo OAuth flow", - "parameters": [ - { - "description": "Optional card ID for re-authentication", - "name": "request", - "in": "body", - "schema": { - "$ref": "#/definitions/cards.TuyoConnectRequest" - } - } - ], - "responses": { - "200": { - "description": "Authorization URL", - "schema": { - "$ref": "#/definitions/cards.TuyoConnectResponse" - } - }, - "400": { - "description": "Invalid request", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "403": { - "description": "Card does not belong to user", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "404": { - "description": "Card not found", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/miso/cards/{cardId}": { - "delete": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Soft deletes a card belonging to the authenticated user", - "produces": [ - "application/json" - ], - "tags": [ - "Miso" - ], - "summary": "Delete a card", - "parameters": [ - { - "minimum": 1, - "type": "integer", - "description": "Card ID", - "name": "cardId", - "in": "path", - "required": true - } - ], - "responses": { - "204": { - "description": "Card deleted successfully" - }, - "400": { - "description": "Invalid card ID", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "403": { - "description": "Card does not belong to user", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "404": { - "description": "Card not found", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - }, - "patch": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Updates the nickname of a card belonging to the authenticated user", - "consumes": [ - "application/json" - ], - "tags": [ - "Miso" - ], - "summary": "Rename a card", - "parameters": [ - { - "minimum": 1, - "type": "integer", - "description": "Card ID", - "name": "cardId", - "in": "path", - "required": true - }, - { - "description": "New card name", - "name": "request", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/cards.RenameCardRequest" - } - } - ], - "responses": { - "204": { - "description": "Card renamed successfully" - }, - "400": { - "description": "Invalid request body or validation error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "403": { - "description": "Card does not belong to user", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "404": { - "description": "Card not found", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/miso/referral/validate": { - "post": { - "description": "Checks if a referral code exists and is available for use", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Miso" - ], - "summary": "Validate referral code", - "parameters": [ - { - "description": "Referral code to validate", - "name": "request", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/miso.ValidateReferralRequest" - } - } - ], - "responses": { - "200": { - "description": "Code validation result", - "schema": { - "$ref": "#/definitions/miso.ValidateReferralResponse" - } - }, - "400": { - "description": "Invalid request or code", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/miso/register": { - "post": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Registers a new user after Privy authentication and smart wallet deployment.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Miso" - ], - "summary": "Register a new user", - "parameters": [ - { - "description": "Registration details", - "name": "request", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/miso.RegisterRequest" - } - } - ], - "responses": { - "201": { - "description": "User successfully registered", - "schema": { - "$ref": "#/definitions/miso.RegisterResponse" - } - }, - "400": { - "description": "Invalid request body, validation error, or invalid referral code", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "409": { - "description": "User already exists", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/miso/user": { - "get": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Returns the authenticated user's profile including associated cards and referral info", - "produces": [ - "application/json" - ], - "tags": [ - "Miso" - ], - "summary": "Get user profile", - "responses": { - "200": { - "description": "User profile retrieved successfully", - "schema": { - "$ref": "#/definitions/miso.UserResponse" - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "404": { - "description": "User not found", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/miso/username/check": { - "post": { - "description": "Returns 200 if username is available, 409 if already taken", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Miso" - ], - "summary": "Check username availability", - "parameters": [ - { - "description": "Username to check", - "name": "request", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/miso.CheckUsernameRequest" - } - } - ], - "responses": { - "200": { - "description": "Username is available", - "schema": { - "$ref": "#/definitions/miso.CheckUsernameResponse" - } - }, - "400": { - "description": "Invalid request body or validation error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "409": { - "description": "Username already taken", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - } - }, - "definitions": { - "cards.CardResponse": { - "type": "object", - "required": [ - "authStatus", - "balances", - "id", - "name", - "topupAddress", - "topupChain", - "totalUsdBalance", - "type" - ], - "properties": { - "authStatus": { - "description": "Authentication status: \"ok\" or \"needs_reauth\"", - "type": "string", - "example": "ok" - }, - "balances": { - "description": "Token balances", - "type": "array", - "items": { - "$ref": "#/definitions/cards.TokenBalanceResponse" - } - }, - "id": { - "description": "Unique card identifier", - "type": "integer", - "example": 1 - }, - "name": { - "description": "User-defined card name", - "type": "string", - "example": "My Card" - }, - "topupAddress": { - "description": "Address for topping up the card", - "type": "string", - "example": "0x1234567890abcdef1234567890abcdef12345678" - }, - "topupChain": { - "description": "CAIP-2 chain for topup transactions", - "type": "string", - "example": "eip155:8453" - }, - "totalUsdBalance": { - "description": "Total USD value across all token balances", - "type": "number", - "example": 1234.56 - }, - "type": { - "description": "Card provider type", - "type": "string", - "example": "tuyo" - } - } - }, - "cards.CardsResponse": { - "type": "object", - "required": [ - "cards" - ], - "properties": { - "cards": { - "description": "List of user's cards", - "type": "array", - "items": { - "$ref": "#/definitions/cards.CardResponse" - } - } - } - }, - "cards.CreateCardRequest": { - "type": "object", - "required": [ - "cardName", - "cardType", - "topupAddress", - "topupChain" - ], - "properties": { - "cardName": { - "description": "User-defined card name", - "type": "string", - "maxLength": 30, - "minLength": 1, - "example": "My Card" - }, - "cardType": { - "description": "Card provider type", - "type": "string", - "example": "tuyo" - }, - "topupAddress": { - "description": "Address for topping up the card", - "type": "string", - "example": "0x1234567890abcdef1234567890abcdef12345678" - }, - "topupChain": { - "description": "CAIP-2 chain for topup transactions", - "type": "string", - "example": "eip155:8453" - } - } - }, - "cards.RenameCardRequest": { - "type": "object", - "required": [ - "cardName" - ], - "properties": { - "cardName": { - "description": "New card name", - "type": "string", - "maxLength": 30, - "minLength": 1, - "example": "My Renamed Card" - } - } - }, - "cards.TokenBalanceResponse": { - "type": "object", - "required": [ - "token", - "usdPrice", - "usdValue" - ], - "properties": { - "token": { - "description": "Token information (what you hold)", - "allOf": [ - { - "$ref": "#/definitions/cards.TokenInfoResponse" - } - ] - }, - "usdPrice": { - "description": "USD price per unit of the token", - "type": "number", - "example": 1 - }, - "usdValue": { - "description": "Total USD value of the balance", - "type": "number", - "example": 1234.56 - } - } - }, - "cards.TokenInfoResponse": { - "type": "object", - "required": [ - "balance", - "balanceRaw", - "chainCaip", - "decimals", - "symbol" - ], - "properties": { - "balance": { - "description": "Formatted balance with decimals", - "type": "string", - "example": "1234.56" - }, - "balanceRaw": { - "description": "Raw balance in smallest unit (wei)", - "type": "string", - "example": "1234560000" - }, - "chainCaip": { - "description": "CAIP-2 chain identifier (e.g. \"eip155:8453\")", - "type": "string", - "example": "eip155:8453" - }, - "decimals": { - "description": "Token decimals", - "type": "integer", - "example": 6 - }, - "symbol": { - "description": "Token symbol (e.g. \"usdc\")", - "type": "string", - "example": "usdc" - } - } - }, - "cards.TuyoCallbackRequest": { - "type": "object", - "required": [ - "code", - "state" - ], - "properties": { - "cardName": { - "description": "Name of the Card to add. Required for new card creation, ignored for re-authentication.", - "type": "string", - "maxLength": 30, - "example": "My Card" - }, - "code": { - "description": "OAuth authorization code from Tuyo redirect", - "type": "string", - "example": "abc123" - }, - "state": { - "description": "OAuth state parameter for CSRF protection", - "type": "string", - "example": "a1b2c3d4..." - } - } - }, - "cards.TuyoConnectRequest": { - "type": "object", - "properties": { - "cardId": { - "description": "Card ID for re-authentication flow. Omit for new card creation.", - "type": "integer", - "example": 123 - } - } - }, - "cards.TuyoConnectResponse": { - "type": "object", - "required": [ - "authUrl" - ], - "properties": { - "authUrl": { - "description": "The Tuyo OAuth authorization URL to redirect the user to", - "type": "string", - "example": "https://auth.tuyo.com/authorize?..." - } - } - }, - "miso.CheckUsernameRequest": { - "type": "object", - "required": [ - "username" - ], - "properties": { - "username": { - "description": "Username to check availability (3-50 characters)", - "type": "string", - "maxLength": 50, - "minLength": 3, - "example": "johndoe" - } - } - }, - "miso.CheckUsernameResponse": { - "type": "object", - "required": [ - "message" - ], - "properties": { - "message": { - "description": "Availability message", - "type": "string", - "example": "username available" - } - } - }, - "miso.RegisterRequest": { - "type": "object", - "required": [ - "privyDid", - "referralCode", - "smartAccount", - "username" - ], - "properties": { - "privyDid": { - "description": "Privy decentralized identifier", - "type": "string", - "example": "did:privy:abc123" - }, - "referralCode": { - "description": "Referral code (required for registration)", - "type": "string", - "example": "A7K9MX2P" - }, - "smartAccount": { - "description": "Ethereum smart account address", - "type": "string", - "example": "0x1234567890abcdef1234567890abcdef12345678" - }, - "username": { - "description": "Unique username (3-50 characters)", - "type": "string", - "maxLength": 50, - "minLength": 3, - "example": "johndoe" - } - } - }, - "miso.RegisterResponse": { - "type": "object", - "required": [ - "createdAt", - "smartAccount", - "userId", - "username" - ], - "properties": { - "createdAt": { - "description": "Account creation timestamp", - "type": "string", - "example": "2024-01-15T10:30:00Z" - }, - "referralCode": { - "description": "User's personal referral code (empty if creation failed)", - "type": "string", - "example": "B3C8WX4N" - }, - "smartAccount": { - "description": "Ethereum smart account address", - "type": "string", - "example": "0x1234567890abcdef1234567890abcdef12345678" - }, - "userId": { - "description": "Unique user identifier", - "type": "integer", - "example": 1 - }, - "username": { - "description": "User's username", - "type": "string", - "example": "johndoe" - } - } - }, - "miso.UserResponse": { - "type": "object", - "required": [ - "badges", - "cards", - "referralCode", - "referralUsageCount", - "smartAccount", - "username" - ], - "properties": { - "badges": { - "description": "List of user's badge types", - "type": "array", - "items": { - "type": "string" - }, - "example": [ - "founding_member" - ] - }, - "cards": { - "description": "List of user's cards", - "type": "array", - "items": { - "$ref": "#/definitions/cards.CardResponse" - } - }, - "referralCode": { - "description": "User's referral code", - "type": "string", - "example": "B3C8WX4N" - }, - "referralExpiresAt": { - "description": "Referral code expiration timestamp (null = never expires)", - "type": "string", - "example": "2024-12-31T23:59:59Z" - }, - "referralMaxUsage": { - "description": "Maximum allowed uses (null = unlimited)", - "type": "integer", - "example": 10 - }, - "referralUsageCount": { - "description": "Number of times the referral code has been used", - "type": "integer", - "example": 5 - }, - "smartAccount": { - "description": "Ethereum smart account address", - "type": "string", - "example": "0x1234567890abcdef1234567890abcdef12345678" - }, - "username": { - "description": "User's username", - "type": "string", - "example": "johndoe" - } - } - }, - "miso.ValidateReferralRequest": { - "type": "object", - "required": [ - "code" - ], - "properties": { - "code": { - "type": "string", - "example": "A7K9MX2P" - } - } - }, - "miso.ValidateReferralResponse": { - "type": "object", - "required": [ - "valid" - ], - "properties": { - "valid": { - "type": "boolean", - "example": true - } - } - }, - "responses.ErrorResponse": { - "type": "object", - "required": [ - "error" - ], - "properties": { - "debug": { - "type": "string" - }, - "error": { - "type": "string" - } - } - }, - "server.HealthHandler.response": { - "type": "object", - "required": [ - "status" - ], - "properties": { - "status": { - "type": "string" - } - } - } - }, - "securityDefinitions": { - "BearerAuth": { - "description": "Enter your Privy JWT token with the `Bearer ` prefix", - "type": "apiKey", - "name": "Authorization", - "in": "header" - } - } -} \ No newline at end of file diff --git a/api-reference/miso/openapi.json b/api-reference/miso/openapi.json deleted file mode 100644 index a54fe19d..00000000 --- a/api-reference/miso/openapi.json +++ /dev/null @@ -1,1237 +0,0 @@ -{ - "openapi": "3.0.0", - "info": { - "contact": {}, - "title": "", - "version": "" - }, - "servers": [ - { - "url": "https://api.getmiso.fi", - "description": "Production server" - } - ], - "paths": { - "/health": { - "get": { - "description": "health check", - "summary": "health check", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/server.HealthHandler.response" - } - } - } - } - } - } - }, - "/miso/cards": { - "get": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Returns all cards for the authenticated user", - "tags": [ - "Miso" - ], - "summary": "Get user cards", - "responses": { - "200": { - "description": "List of user's cards", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/cards.CardsResponse" - } - } - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "404": { - "description": "User not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "500": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - } - } - }, - "post": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Creates a new card for the authenticated user", - "tags": [ - "Miso" - ], - "summary": "Create a new card", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/cards.CreateCardRequest" - } - } - }, - "description": "Card details", - "required": true - }, - "responses": { - "201": { - "description": "Card created successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/cards.CardResponse" - } - } - } - }, - "400": { - "description": "Invalid request body or validation error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "404": { - "description": "User not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "409": { - "description": "Card already exists", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "500": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - } - } - } - }, - "/miso/cards/tuyo/authorize": { - "post": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Validates the OAuth state, exchanges the authorization code for tokens, and creates a Tuyo card or re-authenticates an existing one.", - "tags": [ - "Miso" - ], - "summary": "Complete Tuyo OAuth flow", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/cards.TuyoCallbackRequest" - } - } - }, - "description": "OAuth callback parameters", - "required": true - }, - "responses": { - "200": { - "description": "Re-authentication successful", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/cards.CardResponse" - } - } - } - }, - "201": { - "description": "Card created successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/cards.CardResponse" - } - } - } - }, - "400": { - "description": "Invalid request, state, or authorization code", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "404": { - "description": "User not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "409": { - "description": "Tuyo account already connected", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "500": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "502": { - "description": "Tuyo service unavailable", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - } - } - } - }, - "/miso/cards/tuyo/create": { - "post": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Generates an OAuth state and returns the Tuyo authorization URL. If cardId is provided, initiates re-authentication for an existing card.", - "tags": [ - "Miso" - ], - "summary": "Initiate Tuyo OAuth flow", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/cards.TuyoConnectRequest" - } - } - }, - "description": "Optional card ID for re-authentication" - }, - "responses": { - "200": { - "description": "Authorization URL", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/cards.TuyoConnectResponse" - } - } - } - }, - "400": { - "description": "Invalid request", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "403": { - "description": "Card does not belong to user", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "404": { - "description": "Card not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "500": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - } - } - } - }, - "/miso/cards/{cardId}": { - "delete": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Soft deletes a card belonging to the authenticated user", - "tags": [ - "Miso" - ], - "summary": "Delete a card", - "parameters": [ - { - "description": "Card ID", - "name": "cardId", - "in": "path", - "required": true, - "schema": { - "type": "integer", - "minimum": 1 - } - } - ], - "responses": { - "204": { - "description": "Card deleted successfully" - }, - "400": { - "description": "Invalid card ID", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "403": { - "description": "Card does not belong to user", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "404": { - "description": "Card not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "500": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - } - } - }, - "patch": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Updates the nickname of a card belonging to the authenticated user", - "tags": [ - "Miso" - ], - "summary": "Rename a card", - "parameters": [ - { - "description": "Card ID", - "name": "cardId", - "in": "path", - "required": true, - "schema": { - "type": "integer", - "minimum": 1 - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/cards.RenameCardRequest" - } - } - }, - "description": "New card name", - "required": true - }, - "responses": { - "204": { - "description": "Card renamed successfully" - }, - "400": { - "description": "Invalid request body or validation error", - "content": { - "*/*": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "content": { - "*/*": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "403": { - "description": "Card does not belong to user", - "content": { - "*/*": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "404": { - "description": "Card not found", - "content": { - "*/*": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "500": { - "description": "Internal server error", - "content": { - "*/*": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - } - } - } - }, - "/miso/referral/validate": { - "post": { - "description": "Checks if a referral code exists and is available for use", - "tags": [ - "Miso" - ], - "summary": "Validate referral code", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/miso.ValidateReferralRequest" - } - } - }, - "description": "Referral code to validate", - "required": true - }, - "responses": { - "200": { - "description": "Code validation result", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/miso.ValidateReferralResponse" - } - } - } - }, - "400": { - "description": "Invalid request or code", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "500": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - } - } - } - }, - "/miso/register": { - "post": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Registers a new user after Privy authentication and smart wallet deployment.", - "tags": [ - "Miso" - ], - "summary": "Register a new user", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/miso.RegisterRequest" - } - } - }, - "description": "Registration details", - "required": true - }, - "responses": { - "201": { - "description": "User successfully registered", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/miso.RegisterResponse" - } - } - } - }, - "400": { - "description": "Invalid request body, validation error, or invalid referral code", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "409": { - "description": "User already exists", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "500": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - } - } - } - }, - "/miso/user": { - "get": { - "security": [ - { - "BearerAuth": [] - } - ], - "description": "Returns the authenticated user's profile including associated cards and referral info", - "tags": [ - "Miso" - ], - "summary": "Get user profile", - "responses": { - "200": { - "description": "User profile retrieved successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/miso.UserResponse" - } - } - } - }, - "401": { - "description": "Unauthorized - missing or invalid authentication", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "404": { - "description": "User not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "500": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - } - } - } - }, - "/miso/username/check": { - "post": { - "description": "Returns 200 if username is available, 409 if already taken", - "tags": [ - "Miso" - ], - "summary": "Check username availability", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/miso.CheckUsernameRequest" - } - } - }, - "description": "Username to check", - "required": true - }, - "responses": { - "200": { - "description": "Username is available", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/miso.CheckUsernameResponse" - } - } - } - }, - "400": { - "description": "Invalid request body or validation error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "409": { - "description": "Username already taken", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - }, - "500": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/responses.ErrorResponse" - } - } - } - } - } - } - } - }, - "components": { - "securitySchemes": { - "BearerAuth": { - "description": "Enter your Privy JWT token with the `Bearer ` prefix", - "type": "apiKey", - "name": "Authorization", - "in": "header" - } - }, - "schemas": { - "cards.CardResponse": { - "type": "object", - "required": [ - "authStatus", - "balances", - "id", - "name", - "topupAddress", - "topupChain", - "totalUsdBalance", - "type" - ], - "properties": { - "authStatus": { - "description": "Authentication status: \"ok\" or \"needs_reauth\"", - "type": "string", - "example": "ok" - }, - "balances": { - "description": "Token balances", - "type": "array", - "items": { - "$ref": "#/components/schemas/cards.TokenBalanceResponse" - } - }, - "id": { - "description": "Unique card identifier", - "type": "integer", - "example": 1 - }, - "name": { - "description": "User-defined card name", - "type": "string", - "example": "My Card" - }, - "topupAddress": { - "description": "Address for topping up the card", - "type": "string", - "example": "0x1234567890abcdef1234567890abcdef12345678" - }, - "topupChain": { - "description": "CAIP-2 chain for topup transactions", - "type": "string", - "example": "eip155:8453" - }, - "totalUsdBalance": { - "description": "Total USD value across all token balances", - "type": "number", - "example": 1234.56 - }, - "type": { - "description": "Card provider type", - "type": "string", - "example": "tuyo" - } - } - }, - "cards.CardsResponse": { - "type": "object", - "required": [ - "cards" - ], - "properties": { - "cards": { - "description": "List of user's cards", - "type": "array", - "items": { - "$ref": "#/components/schemas/cards.CardResponse" - } - } - } - }, - "cards.CreateCardRequest": { - "type": "object", - "required": [ - "cardName", - "cardType", - "topupAddress", - "topupChain" - ], - "properties": { - "cardName": { - "description": "User-defined card name", - "type": "string", - "maxLength": 30, - "minLength": 1, - "example": "My Card" - }, - "cardType": { - "description": "Card provider type", - "type": "string", - "example": "tuyo" - }, - "topupAddress": { - "description": "Address for topping up the card", - "type": "string", - "example": "0x1234567890abcdef1234567890abcdef12345678" - }, - "topupChain": { - "description": "CAIP-2 chain for topup transactions", - "type": "string", - "example": "eip155:8453" - } - } - }, - "cards.RenameCardRequest": { - "type": "object", - "required": [ - "cardName" - ], - "properties": { - "cardName": { - "description": "New card name", - "type": "string", - "maxLength": 30, - "minLength": 1, - "example": "My Renamed Card" - } - } - }, - "cards.TokenBalanceResponse": { - "type": "object", - "required": [ - "token", - "usdPrice", - "usdValue" - ], - "properties": { - "token": { - "description": "Token information (what you hold)", - "allOf": [ - { - "$ref": "#/components/schemas/cards.TokenInfoResponse" - } - ] - }, - "usdPrice": { - "description": "USD price per unit of the token", - "type": "number", - "example": 1 - }, - "usdValue": { - "description": "Total USD value of the balance", - "type": "number", - "example": 1234.56 - } - } - }, - "cards.TokenInfoResponse": { - "type": "object", - "required": [ - "balance", - "balanceRaw", - "chainCaip", - "decimals", - "symbol" - ], - "properties": { - "balance": { - "description": "Formatted balance with decimals", - "type": "string", - "example": "1234.56" - }, - "balanceRaw": { - "description": "Raw balance in smallest unit (wei)", - "type": "string", - "example": "1234560000" - }, - "chainCaip": { - "description": "CAIP-2 chain identifier (e.g. \"eip155:8453\")", - "type": "string", - "example": "eip155:8453" - }, - "decimals": { - "description": "Token decimals", - "type": "integer", - "example": 6 - }, - "symbol": { - "description": "Token symbol (e.g. \"usdc\")", - "type": "string", - "example": "usdc" - } - } - }, - "cards.TuyoCallbackRequest": { - "type": "object", - "required": [ - "code", - "state" - ], - "properties": { - "cardName": { - "description": "Name of the Card to add. Required for new card creation, ignored for re-authentication.", - "type": "string", - "maxLength": 30, - "example": "My Card" - }, - "code": { - "description": "OAuth authorization code from Tuyo redirect", - "type": "string", - "example": "abc123" - }, - "state": { - "description": "OAuth state parameter for CSRF protection", - "type": "string", - "example": "a1b2c3d4..." - } - } - }, - "cards.TuyoConnectRequest": { - "type": "object", - "properties": { - "cardId": { - "description": "Card ID for re-authentication flow. Omit for new card creation.", - "type": "integer", - "example": 123 - } - } - }, - "cards.TuyoConnectResponse": { - "type": "object", - "required": [ - "authUrl" - ], - "properties": { - "authUrl": { - "description": "The Tuyo OAuth authorization URL to redirect the user to", - "type": "string", - "example": "https://auth.tuyo.com/authorize?..." - } - } - }, - "miso.CheckUsernameRequest": { - "type": "object", - "required": [ - "username" - ], - "properties": { - "username": { - "description": "Username to check availability (3-50 characters)", - "type": "string", - "maxLength": 50, - "minLength": 3, - "example": "johndoe" - } - } - }, - "miso.CheckUsernameResponse": { - "type": "object", - "required": [ - "message" - ], - "properties": { - "message": { - "description": "Availability message", - "type": "string", - "example": "username available" - } - } - }, - "miso.RegisterRequest": { - "type": "object", - "required": [ - "privyDid", - "referralCode", - "smartAccount", - "username" - ], - "properties": { - "privyDid": { - "description": "Privy decentralized identifier", - "type": "string", - "example": "did:privy:abc123" - }, - "referralCode": { - "description": "Referral code (required for registration)", - "type": "string", - "example": "A7K9MX2P" - }, - "smartAccount": { - "description": "Ethereum smart account address", - "type": "string", - "example": "0x1234567890abcdef1234567890abcdef12345678" - }, - "username": { - "description": "Unique username (3-50 characters)", - "type": "string", - "maxLength": 50, - "minLength": 3, - "example": "johndoe" - } - } - }, - "miso.RegisterResponse": { - "type": "object", - "required": [ - "createdAt", - "smartAccount", - "userId", - "username" - ], - "properties": { - "createdAt": { - "description": "Account creation timestamp", - "type": "string", - "example": "2024-01-15T10:30:00Z" - }, - "referralCode": { - "description": "User's personal referral code (empty if creation failed)", - "type": "string", - "example": "B3C8WX4N" - }, - "smartAccount": { - "description": "Ethereum smart account address", - "type": "string", - "example": "0x1234567890abcdef1234567890abcdef12345678" - }, - "userId": { - "description": "Unique user identifier", - "type": "integer", - "example": 1 - }, - "username": { - "description": "User's username", - "type": "string", - "example": "johndoe" - } - } - }, - "miso.UserResponse": { - "type": "object", - "required": [ - "badges", - "cards", - "referralCode", - "referralUsageCount", - "smartAccount", - "username" - ], - "properties": { - "badges": { - "description": "List of user's badge types", - "type": "array", - "items": { - "type": "string" - }, - "example": [ - "founding_member" - ] - }, - "cards": { - "description": "List of user's cards", - "type": "array", - "items": { - "$ref": "#/components/schemas/cards.CardResponse" - } - }, - "referralCode": { - "description": "User's referral code", - "type": "string", - "example": "B3C8WX4N" - }, - "referralExpiresAt": { - "description": "Referral code expiration timestamp (null = never expires)", - "type": "string", - "example": "2024-12-31T23:59:59Z" - }, - "referralMaxUsage": { - "description": "Maximum allowed uses (null = unlimited)", - "type": "integer", - "example": 10 - }, - "referralUsageCount": { - "description": "Number of times the referral code has been used", - "type": "integer", - "example": 5 - }, - "smartAccount": { - "description": "Ethereum smart account address", - "type": "string", - "example": "0x1234567890abcdef1234567890abcdef12345678" - }, - "username": { - "description": "User's username", - "type": "string", - "example": "johndoe" - } - } - }, - "miso.ValidateReferralRequest": { - "type": "object", - "required": [ - "code" - ], - "properties": { - "code": { - "type": "string", - "example": "A7K9MX2P" - } - } - }, - "miso.ValidateReferralResponse": { - "type": "object", - "required": [ - "valid" - ], - "properties": { - "valid": { - "type": "boolean", - "example": true - } - } - }, - "responses.ErrorResponse": { - "type": "object", - "required": [ - "error" - ], - "properties": { - "debug": { - "type": "string" - }, - "error": { - "type": "string" - } - } - }, - "server.HealthHandler.response": { - "type": "object", - "required": [ - "status" - ], - "properties": { - "status": { - "type": "string" - } - } - } - } - } -} \ No newline at end of file diff --git a/api-reference/signing/get-confirmations.mdx b/api-reference/signing/get-confirmations.mdx deleted file mode 100644 index 528fa226..00000000 --- a/api-reference/signing/get-confirmations.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "Get Confirmations" -description: "GET /v1/chains/{chainId}/confirmations" ---- - -Returns the number of block confirmations required for deposits on the given chain, bucketed by value ranges. - -## Request - -```bash -curl https://api.getmiso.fi/v1/chains/8453/confirmations -``` - -## Path Parameters - -| Parameter | Type | Description | -|-----------|------|-------------| -| `chainId` | `uint64` | Chain ID to query | - -## Response - -Returns confirmation count requirements bucketed by deposit value thresholds. The exact format depends on the chain configuration. - -```json -{ - "confirmations": [ - {"maxValue": 1000, "blocks": 1}, - {"maxValue": 10000, "blocks": 3}, - {"maxValue": 100000, "blocks": 6} - ] -} -``` - -## Errors - -| Status | Description | -|--------|-------------| -| `400` | Invalid chain ID | -| `404` | Chain not supported | diff --git a/api-reference/signing/get-signing-status.mdx b/api-reference/signing/get-signing-status.mdx deleted file mode 100644 index 4c08b288..00000000 --- a/api-reference/signing/get-signing-status.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "Get Signing Status (SSE)" -description: "GET /v1/chains/{chainId}/signatures/{depositId}" ---- - -Subscribe to the signing result via Server-Sent Events. The connection stays open until the MPC signature is ready, then sends the hex-encoded signature as an SSE `data` event and closes. - -## Request - -```bash -curl -N https://api.getmiso.fi/v1/chains/8453/signatures/12345 \ - -H "Accept: text/event-stream" -``` - -## Path Parameters - -| Parameter | Type | Description | -|-----------|------|-------------| -| `chainId` | `uint64` | Chain ID (must be supported) | -| `depositId` | `string` | Deposit ID from the signing request | - -## Response - -**Content-Type:** `text/event-stream` - -The response is an SSE stream. When the signature is ready: - -``` -data: -``` - -### Example SSE Response - -``` -data: a1b2c3d4e5f6... -``` - -## Response Headers - -``` -Content-Type: text/event-stream -Cache-Control: no-cache -Connection: keep-alive -Access-Control-Allow-Origin: * -``` - -## Errors - -| Status | Description | -|--------|-------------| -| `400` | Invalid chain ID or missing deposit ID | -| `404` | Chain not supported | - -## Usage with JavaScript - -```javascript -const eventSource = new EventSource( - 'https://api.getmiso.fi/v1/chains/8453/signatures/12345' -); - -eventSource.onmessage = (event) => { - const signature = event.data; - console.log('Signature:', signature); - eventSource.close(); -}; -``` diff --git a/api-reference/signing/introduction.mdx b/api-reference/signing/introduction.mdx deleted file mode 100644 index cadb75ff..00000000 --- a/api-reference/signing/introduction.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: "Signing API" -description: "MPC threshold signing service for cross-chain operations" ---- - -## Base URL - -``` -https://api.getmiso.fi -``` - -## Authentication - -No API key required. Requests are validated by chain ID and protocol type. - -## Supported Protocols - -| Protocol | Value | Description | -|----------|-------|-------------| -| Across | `across` | Across bridge deposits | -| Mayan | `mayan` | Mayan swap protocol | -| Rhinestone | `rhinestone` | Rhinestone module bundles | -| LiFi Escrow | `lifi-escrow` | LiFi escrow orders | -| Lighter | `lighter` | Lighter protocol orders | -| Sprinter Credit | `sprinter-credit` | Sprinter credit line operations | - -## Response Format - -- `POST /signatures` returns `202 Accepted` on success (async signing) -- `GET /signatures/{depositId}` uses **Server-Sent Events (SSE)** — the connection stays open until the signature is ready -- `POST /unlocks` returns `200` with the signature synchronously (15s timeout) - -## Go Types - -```go -type ProtocolType string - -const ( - AcrossProtocol ProtocolType = "across" - MayanProtocol ProtocolType = "mayan" - RhinestoneProtocol ProtocolType = "rhinestone" - LifiEscrowProtocol ProtocolType = "lifi-escrow" - LighterProtocol ProtocolType = "lighter" - SprinterCreditProtocol ProtocolType = "sprinter-credit" -) -``` diff --git a/api-reference/signing/request-unlock.mdx b/api-reference/signing/request-unlock.mdx deleted file mode 100644 index 20d64de9..00000000 --- a/api-reference/signing/request-unlock.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: "Request Unlock Signature" -description: "POST /v1/chains/{chainId}/unlocks" ---- - -Request an MPC unlock signature. This is a synchronous call with a 15-second timeout — the signature is returned directly in the response body. - -Currently only supports the `lifi-escrow` protocol. - -## Request - -```bash -curl -X POST https://api.getmiso.fi/v1/chains/8453/unlocks \ - -H "Content-Type: application/json" \ - -d '{ - "protocol": "lifi-escrow", - "orderId": "0xabc123...", - "settler": "0x1234567890abcdef1234567890abcdef12345678" - }' -``` - -## Path Parameters - -| Parameter | Type | Description | -|-----------|------|-------------| -| `chainId` | `uint64` | Chain ID (must be supported) | - -## Request Body - -```go -type UnlockBody struct { - Protocol ProtocolType `json:"protocol"` // Currently only "lifi-escrow" - OrderID string `json:"orderId"` // Order ID to unlock - Settler string `json:"settler"` // Settler contract address -} -``` - -## Response - -```json -{ - "signature": "a1b2c3d4e5f6...", - "id": "unlock-123" -} -``` - -```go -type UnlockResponse struct { - Signature string `json:"signature"` // Hex-encoded ECDSA signature - ID string `json:"id"` // Unlock identifier -} -``` - -## Errors - -| Status | Description | -|--------|-------------| -| `400` | Invalid request body or unsupported chain/protocol | -| `500` | Signing timeout (15s) or invalid signature | diff --git a/api-reference/signing/submit-signing.mdx b/api-reference/signing/submit-signing.mdx deleted file mode 100644 index c56c1a74..00000000 --- a/api-reference/signing/submit-signing.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "Submit Signing Request" -description: "POST /v1/chains/{chainId}/signatures" ---- - -Submit a deposit for MPC threshold signing. Returns `202 Accepted` if the deposit is accepted for signing, or an error if signing fails. - -## Request - -```bash -curl -X POST https://api.getmiso.fi/v1/chains/8453/signatures \ - -H "Content-Type: application/json" \ - -d '{ - "depositId": "12345", - "nonce": "1", - "protocol": "across", - "liquidityPool": "0x1234567890abcdef1234567890abcdef12345678", - "caller": "0xabcdef1234567890abcdef1234567890abcdef12", - "calldata": "", - "depositTxHash": "0xabc123...", - "borrowAmount": "1000000", - "repaymentChainId": 1, - "deadline": 1735689600, - "tokenOut": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" - }' -``` - -## Path Parameters - -| Parameter | Type | Description | -|-----------|------|-------------| -| `chainId` | `uint64` | Destination chain ID (must be supported) | - -## Request Body - -```go -type SigningBody struct { - DepositId string `json:"depositId"` // Deposit identifier (format varies by protocol) - Nonce *BigInt `json:"nonce"` // Signing nonce - Protocol ProtocolType `json:"protocol"` // Protocol type (see introduction) - LiquidityPool string `json:"liquidityPool"` // Liquidity pool contract address - Caller string `json:"caller"` // Caller contract address - Calldata string `json:"calldata"` // Optional calldata (used by mayan, lifi-escrow, sprinter-credit) - DepositTxHash string `json:"depositTxHash"` // Source chain deposit transaction hash - BorrowAmount *BigInt `json:"borrowAmount"` // Amount to borrow - RepaymentChainId uint64 `json:"repaymentChainId"` // Chain where repayment happens - Deadline uint64 `json:"deadline"` // Unix timestamp deadline - TokenOut string `json:"tokenOut"` // Output token address (sprinter-credit only) -} -``` - -## Required Fields - -All protocols require: `depositId`, `nonce`, `protocol`, `liquidityPool`, `caller`, `deadline`, `chainId`. - -## Responses - -| Status | Description | -|--------|-------------| -| `202` | Deposit accepted for signing | -| `400` | Invalid request body or unsupported chain/protocol | -| `500` | Signing failed | - -## Protocol-Specific Notes - -- **across**: `depositId` is a numeric string, `borrowAmount` required -- **mayan**: `depositId` is an order hash, `calldata` and `depositTxHash` required -- **rhinestone**: `depositId` is a bundle ID, `borrowAmount` required -- **lifi-escrow**: `depositId` is an order ID, `calldata` and `depositTxHash` required -- **lighter**: `depositId` is an order hash, `depositTxHash` required -- **sprinter-credit**: `tokenOut` and `calldata` required, `borrowAmount` required diff --git a/api-reference/sprinter/openapi-v2.json b/api-reference/sprinter/openapi-v2.json deleted file mode 100644 index 8bcdb97a..00000000 --- a/api-reference/sprinter/openapi-v2.json +++ /dev/null @@ -1,1987 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "contact": {} - }, - "paths": { - "/credit/accounts/{account}/draw": { - "get": { - "description": "Returns the calls needed to draw credit. If the user has sufficient\nregistered collateral, the drawCredit call is returned.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Credit" - ], - "summary": "Build transaction calls to draw credit", - "parameters": [ - { - "type": "string", - "description": "User account address (borrower)", - "name": "account", - "in": "path", - "required": true - }, - { - "type": "string", - "description": "Amount to borrow (in wei)", - "name": "amount", - "in": "query", - "required": true - }, - { - "type": "string", - "description": "Address to receive the borrowed funds", - "name": "receiver", - "in": "query", - "required": true - } - ], - "responses": { - "200": { - "description": "List of contract calls to execute drawing credit", - "schema": { - "$ref": "#/definitions/credit.DrawCredit.response" - } - }, - "400": { - "description": "Bad request due to invalid input or insufficient collateral", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "401": { - "description": "Unauthorized", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/credit/accounts/{account}/info": { - "get": { - "description": "Returns credit details including collateral value, debt, health factor, interest, principal, and due date for a user account across all credit tokens", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Credit" - ], - "summary": "Get user credit information", - "parameters": [ - { - "type": "string", - "example": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", - "description": "Ethereum account address", - "name": "account", - "in": "path", - "required": true - } - ], - "responses": { - "200": { - "description": "User credit information", - "schema": { - "$ref": "#/definitions/credit.GetCreditUserInfo.response" - } - }, - "400": { - "description": "Invalid account address", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/credit/accounts/{account}/lock": { - "get": { - "description": "Creates list of contract calls to lock assets as collateral for credit account. Supports both underlying assets (e.g., USDC) which are wrapped into earn vault first, and earn positions (e.g., gtUSDCp) which are deposited directly.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Credit" - ], - "summary": "Calldata to lock asset as collateral", - "parameters": [ - { - "type": "string", - "description": "Account that holds the asset and will execute calls", - "name": "account", - "in": "path", - "required": true - }, - { - "type": "string", - "description": "Amount in lowest denomination (e.g., wei for ETH)", - "name": "amount", - "in": "query", - "required": true - }, - { - "type": "string", - "description": "Asset address in eth format - either underlying asset (USDC) or earn position (gtUSDCp)", - "name": "asset", - "in": "query", - "required": true - }, - { - "type": "string", - "description": "Earn strategy to wrap asset before depositing. If omitted, asset is deposited directly without wrapping.", - "name": "earn", - "in": "query" - } - ], - "responses": { - "200": { - "description": "List of contract calls to execute locking of collateral", - "schema": { - "$ref": "#/definitions/credit.Lock.response" - } - }, - "400": { - "description": "Bad request due to invalid input or missing parameters", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/credit/accounts/{account}/repay": { - "get": { - "description": "Creates list of contract calls to approve USDC and repay debt to CreditHub", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Credit" - ], - "summary": "Call data to repay credit debt", - "parameters": [ - { - "type": "string", - "description": "Account (borrower) that will repay the debt", - "name": "account", - "in": "path", - "required": true - }, - { - "type": "string", - "description": "Amount in lowest denomination (e.g., wei for ETH)", - "name": "amount", - "in": "query", - "required": true - } - ], - "responses": { - "200": { - "description": "List of contract calls to execute repayment", - "schema": { - "$ref": "#/definitions/credit.Repay.response" - } - }, - "400": { - "description": "Bad request due to invalid input or missing parameters", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/credit/accounts/{account}/unlock": { - "get": { - "description": "Creates list of contract calls to unlock and withdraw\ncollateral and potentially unwrap position from earn vault", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Credit" - ], - "summary": "Call data to unlock collateral", - "parameters": [ - { - "type": "string", - "description": "Account that holds the asset and will execute calls", - "name": "account", - "in": "path", - "required": true - }, - { - "type": "string", - "description": "Amount in lowest denomination (e.g., wei for ETH)", - "name": "amount", - "in": "query", - "required": true - }, - { - "type": "string", - "description": "Asset address in eth format", - "name": "asset", - "in": "query", - "required": true - }, - { - "type": "boolean", - "description": "Whether to generate call to unwrap from earn strategy", - "name": "unwrap", - "in": "query" - } - ], - "responses": { - "200": { - "description": "List of contract calls to execute unlocking of collateral", - "schema": { - "$ref": "#/definitions/credit.Unlock.response" - } - }, - "400": { - "description": "Bad request due to invalid input or missing parameters", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/credit/collateral/{chain}/{collateral}": { - "get": { - "description": "Returns detailed information about a collateral asset including APY estimate (if earn vault), price in USD, underlying asset, and earn service name", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Credit" - ], - "summary": "Get collateral asset details", - "parameters": [ - { - "type": "string", - "example": "eip155:8453", - "description": "Chain ID in CAIP-2 format", - "name": "chain", - "in": "path", - "required": true - }, - { - "type": "string", - "example": "0xeE8F4eC5672F09119b96Ab6fB59C27E1b7e44b61", - "description": "Collateral asset address", - "name": "collateral", - "in": "path", - "required": true - } - ], - "responses": { - "200": { - "description": "OK", - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/definitions/credit.CollateralDetailsResponse" - } - } - } - }, - "400": { - "description": "Invalid parameters", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "404": { - "description": "Collateral not supported", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/credit/earn/unwrap": { - "get": { - "description": "Creates list of contract calls to unwrap a position from an earn vault,\nconverting vault shares back to the underlying asset.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Credit" - ], - "summary": "Unwrap position from earn vault", - "parameters": [ - { - "type": "string", - "example": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", - "description": "Owner address that holds the vault shares", - "name": "owner", - "in": "query", - "required": true - }, - { - "type": "string", - "example": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", - "description": "Address that will receive the unwrapped underlying tokens", - "name": "receiver", - "in": "query", - "required": true - }, - { - "type": "string", - "example": "1000000000000000000", - "description": "Amount of shares to unwrap", - "name": "amount", - "in": "query", - "required": true - }, - { - "type": "string", - "example": "0xeE8F4eC5672F09119b96Ab6fB59C27E1b7e44b61", - "description": "Vault shares token address", - "name": "asset", - "in": "query", - "required": true - }, - { - "type": "number", - "default": 0.3, - "description": "Slippage tolerance in percent (e.g. 0.5 = 0.5%)", - "name": "slippage", - "in": "query" - }, - { - "type": "string", - "example": "eip155:8453", - "description": "Chain ID in CAIP format", - "name": "chain", - "in": "query", - "required": true - } - ], - "responses": { - "200": { - "description": "OK", - "schema": { - "$ref": "#/definitions/credit.UnwrapResponse" - } - }, - "400": { - "description": "Invalid input parameters", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/credit/earn/wrap": { - "get": { - "description": "Creates a list of contract calls (approve + deposit) to wrap an\nunderlying token into an earn vault and receive vault shares.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Credit" - ], - "summary": "Wrap asset into earn vault", - "parameters": [ - { - "type": "string", - "example": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", - "description": "Account providing the underlying asset", - "name": "account", - "in": "query", - "required": true - }, - { - "type": "string", - "example": "1000000000000000000", - "description": "Amount of underlying asset to wrap", - "name": "amount", - "in": "query", - "required": true - }, - { - "type": "string", - "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", - "description": "Underlying token address", - "name": "token", - "in": "query", - "required": true - }, - { - "type": "string", - "example": "gauntlet-usdc-prime", - "description": "Earn strategy identifier", - "name": "earn", - "in": "query" - }, - { - "type": "string", - "example": "eip155:8453", - "description": "Chain CAIP-2 identifier", - "name": "chain", - "in": "query", - "required": true - } - ], - "responses": { - "200": { - "description": "OK", - "schema": { - "$ref": "#/definitions/credit.WrapResponse" - } - }, - "400": { - "description": "Invalid input parameters", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/credit/protocol": { - "get": { - "description": "Returns the credit protocol configuration including credit hubs and assets", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Credit" - ], - "summary": "Get credit protocol configuration", - "responses": { - "200": { - "description": "OK", - "schema": { - "$ref": "#/definitions/config.CreditProtocolConfig" - } - }, - "401": { - "description": "Unauthorized - invalid or missing API key", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/health": { - "get": { - "description": "health check", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "summary": "health check", - "responses": { - "200": { - "description": "OK", - "schema": { - "$ref": "#/definitions/server.HealthHandler.response" - } - } - } - } - }, - "/liquidity/chain/{chainId}/tokens": { - "get": { - "description": "Returns a map of token symbols to token metadata supported by Stash on the specified chain.", - "produces": [ - "application/json" - ], - "tags": [ - "Liquidity" - ], - "summary": "Returns supported tokens for a chain", - "parameters": [ - { - "type": "string", - "description": "Chain ID in CAIP format (e.g., eip155:8453)", - "name": "chainId", - "in": "path", - "required": true - } - ], - "responses": { - "200": { - "description": "Map of token symbols to token metadata\".", - "schema": { - "$ref": "#/definitions/liquidity.GetStashSupportedTokensHandler.response" - } - }, - "400": { - "description": "Bad Request", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/liquidity/pools/events": { - "get": { - "description": "Opens a Server-Sent Events stream that pushes liquidity updates\nwhenever a reservation is created, replaced, or deleted.\nAll query parameters are optional filters.", - "consumes": [ - "application/json" - ], - "produces": [ - "text/event-stream" - ], - "tags": [ - "Liquidity" - ], - "summary": "Stream available liquidity updates via SSE", - "parameters": [ - { - "enum": [ - "aave", - "aave_v2", - "usdc", - "usdc_v2", - "aave_long_term", - "aave_long_term_v2" - ], - "type": "string", - "description": "Pool type filter", - "name": "poolType", - "in": "query" - }, - { - "type": "string", - "example": "eip155:1", - "description": "CAIP chain ID filter", - "name": "chain", - "in": "query" - }, - { - "type": "string", - "example": "USDC", - "description": "Token symbol filter", - "name": "tokenSymbol", - "in": "query" - } - ], - "responses": { - "200": { - "description": "SSE stream of LiquidityEvent objects", - "schema": { - "type": "string" - } - } - } - } - }, - "/liquidity/pools/{poolType}": { - "get": { - "description": "Returns the pool address and available balance for the requested chain and token", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Liquidity" - ], - "summary": "Get available liquidity for a specific pool type on a chain", - "parameters": [ - { - "enum": [ - "aave", - "aave_v2", - "usdc", - "usdc_v2", - "aave_long_term", - "aave_long_term_v2" - ], - "type": "string", - "description": "Pool type", - "name": "poolType", - "in": "path", - "required": true - }, - { - "type": "string", - "example": "eip155:1", - "description": "CAIP chain ID", - "name": "chain", - "in": "query", - "required": true - }, - { - "type": "string", - "example": "USDC", - "description": "Token symbol", - "name": "tokenSymbol", - "in": "query", - "required": true - } - ], - "responses": { - "200": { - "description": "Successfully retrieved available liquidity", - "schema": { - "$ref": "#/definitions/liquidity.availableLiquidityResponse" - } - }, - "400": { - "description": "Bad request due to invalid input or missing parameters", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/liquidity/protocol/{protocol}/fees": { - "get": { - "description": "Returns configured fee and min/max limits from solver config", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Liquidity" - ], - "summary": "Get fee and limits for a given protocol route", - "parameters": [ - { - "type": "string", - "description": "Protocol name", - "name": "protocol", - "in": "path", - "required": true - }, - { - "type": "string", - "description": "Source chain CAIP ID (e.g. \\", - "name": "srcChain", - "in": "query", - "required": true - }, - { - "type": "string", - "description": "Destination chain CAIP ID", - "name": "dstChain", - "in": "query", - "required": true - }, - { - "type": "string", - "description": "Source token symbol or address", - "name": "srcToken", - "in": "query", - "required": true - }, - { - "type": "string", - "description": "Destination token symbol or address", - "name": "dstToken", - "in": "query", - "required": true - } - ], - "responses": { - "200": { - "description": "OK", - "schema": { - "$ref": "#/definitions/liquidity.FeesResponse" - } - }, - "400": { - "description": "Bad Request", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "404": { - "description": "Not Found", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/liquidity/v1/chain/{chain}/protocol/{protocol}/unlock": { - "post": { - "description": "This endpoint returns signed authorization for an unlock transaction", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Liquidity" - ], - "summary": "Get signing authorization for a an unlock transaction", - "parameters": [ - { - "description": "request", - "name": "request", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/liquidity.Unlock" - } - }, - { - "type": "string", - "description": "Name of the protocol, e.g., Across, Lighter", - "name": "protocol", - "in": "path", - "required": true - }, - { - "type": "string", - "description": "ID of the order that is to be unlocked", - "name": "orderId", - "in": "path", - "required": true - } - ], - "responses": { - "200": { - "description": "OK", - "schema": { - "$ref": "#/definitions/liquidity.UnlockResponse" - } - }, - "400": { - "description": "Bad request due to invalid input or missing parameters", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/liquidity/v2/chain/{dstChain}/protocol/{protocol}/signature": { - "post": { - "description": "This endpoint streams signed authorization for a liquidity transaction", - "consumes": [ - "application/json" - ], - "produces": [ - "text/event-stream" - ], - "tags": [ - "Liquidity" - ], - "summary": "Get signing authorization for a liquidity transaction", - "parameters": [ - { - "description": "request", - "name": "request", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/liquidity.BorrowSignatureV2.body" - } - }, - { - "type": "string", - "description": "Name of the protocol, e.g., Across, Lighter", - "name": "protocol", - "in": "path", - "required": true - }, - { - "type": "string", - "description": "Destination chain Caip id, eg. eip155:8453", - "name": "dstChain", - "in": "path", - "required": true - } - ], - "responses": { - "200": { - "description": "This response is sent as a stringified json in SSE event with the event name 'data'", - "schema": { - "$ref": "#/definitions/liquidity.BorrowSignatureResponse" - } - }, - "400": { - "description": "Bad request due to invalid input or missing parameters", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/liquidity/v2/chain/{srcChain}/protocol/{protocol}/type/{type}/quote": { - "get": { - "description": "Calculates the borrow quote including borrow cost, required input/output, and duration", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "tags": [ - "Liquidity" - ], - "summary": "Get the borrow quote for a liquidity transaction based on the input data", - "parameters": [ - { - "type": "string", - "description": "Protocol name (e.g., Across)", - "name": "protocol", - "in": "path", - "required": true - }, - { - "type": "string", - "description": "Quote algorithm type (e.g., ExactInput, ExactOutput)", - "name": "type", - "in": "path", - "required": true - }, - { - "type": "string", - "description": "Source CAIP chain ID (e.g., eip155:1)", - "name": "srcChain", - "in": "path", - "required": true - }, - { - "type": "string", - "description": "Destination CAIP chain ID (e.g., eip155:1)", - "name": "dstChain", - "in": "query", - "required": true - }, - { - "type": "string", - "description": "Exclusive fill flag (true/false)", - "name": "exclusive", - "in": "query" - }, - { - "type": "string", - "description": "Amount of tokens for which we are requesting borrow quote (in the smallest denomination)", - "name": "amount", - "in": "query", - "required": true - }, - { - "type": "string", - "description": "Token address on destination (hex)", - "name": "token", - "in": "query", - "required": true - }, - { - "type": "string", - "description": "Preferred liquidity pool address to borrow from (hex)", - "name": "pool", - "in": "query" - } - ], - "responses": { - "200": { - "description": "Successfully retrieved borrow quote", - "schema": { - "$ref": "#/definitions/liquidity.borrowQuoteResponse" - } - }, - "400": { - "description": "Bad request due to invalid input or missing parameters", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - }, - "/protocol/{protocol}/solver": { - "get": { - "description": "Returns solver address and time solver will need to fill it.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "summary": "Returns solver address", - "parameters": [ - { - "type": "integer", - "description": "order amount in USD", - "name": "amount", - "in": "query", - "required": true - }, - { - "type": "string", - "description": "destination chain in caip format", - "name": "destinationChainId", - "in": "query", - "required": true - }, - { - "type": "string", - "description": "destination token, either symbol or address", - "name": "destinationToken", - "in": "query", - "required": true - }, - { - "type": "string", - "description": "source chain in caip format", - "name": "sourceChainId", - "in": "query", - "required": true - }, - { - "type": "string", - "description": "source token, either symbol or address", - "name": "sourceToken", - "in": "query", - "required": true - }, - { - "type": "string", - "description": "Protocol on which intent will be executed", - "name": "protocol", - "in": "path", - "required": true - } - ], - "responses": { - "200": { - "description": "OK", - "schema": { - "$ref": "#/definitions/server.GetSolverHandler.response" - } - }, - "400": { - "description": "Bad Request", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - }, - "500": { - "description": "Internal Server Error", - "schema": { - "$ref": "#/definitions/responses.ErrorResponse" - } - } - } - } - } - }, - "definitions": { - "config.ChainConfig": { - "type": "object", - "required": [ - "collateral", - "creditHubs", - "escrowsMetadata", - "strategies", - "wrappedNativeAddress" - ], - "properties": { - "collateral": { - "description": "Asset collateral info per asset ID", - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/config.CollateralDetails" - } - }, - "creditHubs": { - "description": "Credit hub info per token symbol", - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/config.CreditHubInfo" - } - }, - "escrowsMetadata": { - "description": "Escrow metadata for the chain", - "allOf": [ - { - "$ref": "#/definitions/config.EscrowsMetadata" - } - ] - }, - "strategies": { - "description": "Earn vault strategies keyed by strategy name", - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/config.EarnVaultMetadata" - } - }, - "wrappedNativeAddress": { - "description": "Wrapped native token address (e.g., WETH). Zero value means native wrapping is not supported.", - "type": "string", - "example": "0x4200000000000000000000000000000000000006" - } - } - }, - "config.CollateralDetails": { - "type": "object", - "required": [ - "escrowAddress", - "strategy", - "symbol" - ], - "properties": { - "escrowAddress": { - "type": "string", - "example": "0xfedcba0987654321fedcba0987654321fedcba09" - }, - "strategy": { - "allOf": [ - { - "$ref": "#/definitions/entity.EarnStrategy" - } - ], - "example": "gauntlet-usdc-prime" - }, - "symbol": { - "allOf": [ - { - "$ref": "#/definitions/entity.TokenSymbol" - } - ], - "example": "USDC" - } - } - }, - "config.CreditHubInfo": { - "type": "object", - "required": [ - "assetAddress", - "creditHubAddress", - "creditHubControllerAddress" - ], - "properties": { - "assetAddress": { - "type": "string", - "example": "0xabcdef1234567890abcdef1234567890abcdef12" - }, - "creditHubAddress": { - "description": "Credit hub contract address", - "type": "string", - "example": "0x1234567890abcdef1234567890abcdef12345678" - }, - "creditHubControllerAddress": { - "description": "Credit hub controller contract address", - "type": "string", - "example": "0xabcdef1234567890abcdef1234567890abcdef12" - } - } - }, - "config.CreditProtocolConfig": { - "type": "object", - "required": [ - "chains" - ], - "properties": { - "chains": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/config.ChainConfig" - } - } - } - }, - "config.EarnVaultMetadata": { - "type": "object", - "required": [ - "curator", - "name", - "protocol", - "riskScore", - "type", - "underlyingAddress", - "vaultAddress", - "vaultType" - ], - "properties": { - "curator": { - "description": "Curator implementation type (e.g., \"Gauntlet\", \"Yo\")", - "allOf": [ - { - "$ref": "#/definitions/entity.Curator" - } - ], - "example": "Gauntlet" - }, - "name": { - "description": "Earn vault name (e.g., \"Gauntlet USDC Prime\")", - "type": "string", - "example": "Gauntlet USDC Prime" - }, - "protocol": { - "description": "Protocol implementation type (e.g., \"morpho-v1\", \"aave-v3\")", - "allOf": [ - { - "$ref": "#/definitions/entity.Strategy" - } - ], - "example": "morpho-v1" - }, - "riskScore": { - "description": "RiskScore indicates the strategy's risk level (0–10 scale)", - "allOf": [ - { - "$ref": "#/definitions/entity.RiskScore" - } - ], - "example": "5" - }, - "type": { - "description": "Type is strategy type (e.g., \"Lending\")", - "allOf": [ - { - "$ref": "#/definitions/entity.StrategyType" - } - ], - "example": "Lending" - }, - "underlyingAddress": { - "description": "Underlying asset address (e.g., USDC)", - "type": "string", - "example": "0x0000000000000000000000000000000000000000" - }, - "vaultAddress": { - "description": "Earn vault contract address", - "type": "string", - "example": "0x0000000000000000000000000000000000000000" - }, - "vaultType": { - "description": "Earn vault type", - "allOf": [ - { - "$ref": "#/definitions/entity.VaultType" - } - ], - "example": "erc4626" - } - } - }, - "config.EscrowsMetadata": { - "type": "object", - "required": [ - "controller", - "helper" - ], - "properties": { - "controller": { - "description": "Escrow controller contract address", - "type": "string", - "example": "0xabcdef1234567890abcdef1234567890abcdef12" - }, - "helper": { - "description": "Escrow helper contract address", - "type": "string", - "example": "0xabcdef1234567890abcdef1234567890abcdef12" - } - } - }, - "config.Token": { - "type": "object", - "required": [ - "address", - "decimals" - ], - "properties": { - "address": { - "type": "string" - }, - "decimals": { - "type": "integer" - } - } - }, - "credit.CollateralDetailsResponse": { - "type": "object", - "required": [ - "collateralAddress", - "collateralPriceUsd", - "earnServiceName", - "isEarnVault" - ], - "properties": { - "apy": { - "type": "number", - "example": 4.56 - }, - "collateralAddress": { - "type": "string", - "example": "0xeE8F4eC5672F09119b96Ab6fB59C27E1b7e44b61" - }, - "collateralPriceUsd": { - "type": "number", - "example": 1.023456 - }, - "earnServiceName": { - "type": "string", - "example": "Gauntlet" - }, - "isEarnVault": { - "type": "boolean", - "example": true - }, - "underlyingAsset": { - "type": "string", - "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" - }, - "underlyingPriceUsd": { - "type": "number", - "example": 1 - } - } - }, - "credit.DrawCredit.response": { - "type": "object", - "required": [ - "calls" - ], - "properties": { - "calls": { - "type": "array", - "items": { - "$ref": "#/definitions/evm.ContractCall" - } - } - } - }, - "credit.GetCreditUserInfo.response": { - "type": "object", - "required": [ - "data" - ], - "properties": { - "data": { - "description": "map of credit token symbol (e.g., \"USDC\") to user credit info", - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/credit.UserCreditInfoFMT" - } - } - } - }, - "credit.Lock.response": { - "type": "object", - "required": [ - "calls" - ], - "properties": { - "calls": { - "type": "array", - "items": { - "$ref": "#/definitions/evm.ContractCall" - } - } - } - }, - "credit.Repay.response": { - "type": "object", - "required": [ - "calls" - ], - "properties": { - "calls": { - "type": "array", - "items": { - "$ref": "#/definitions/evm.ContractCall" - } - } - } - }, - "credit.Unlock.response": { - "type": "object", - "required": [ - "calls" - ], - "properties": { - "calls": { - "type": "array", - "items": { - "$ref": "#/definitions/evm.ContractCall" - } - } - } - }, - "credit.UnwrapResponse": { - "type": "object", - "required": [ - "amountOut", - "calls", - "minAmountOut", - "tokenOut" - ], - "properties": { - "amountOut": { - "description": "Estimated amount of tokens to receive", - "type": "string", - "example": "1000000" - }, - "calls": { - "description": "List of contract calls to execute the unwrap", - "type": "array", - "items": { - "$ref": "#/definitions/evm.ContractCall" - } - }, - "minAmountOut": { - "description": "Minimum amount of tokens to receive (after slippage)", - "type": "string", - "example": "997000" - }, - "tokenOut": { - "description": "Token address that will be received after unwrapping", - "type": "string", - "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" - } - } - }, - "credit.UserCreditInfoFMT": { - "type": "object", - "required": [ - "debt", - "healthFactor", - "interest", - "liquidationLimit", - "mHealthFactor", - "principal", - "remainingCreditCapacity", - "totalCollateralValue", - "totalCreditCapacity" - ], - "properties": { - "debt": { - "description": "Debt is the total amount of drawn credit plus accrued interest", - "type": "string", - "example": "750.25" - }, - "dueDate": { - "description": "DueDate is the repayment due date (derived from grace period end).\nNull when no active credit exists.", - "type": "string", - "example": "2024-12-31T23:59:59Z" - }, - "healthFactor": { - "description": "HealthFactor indicates liquidation safety\n(e.g. \"0.4044\", \"1.25\")", - "type": "string", - "example": "1.25" - }, - "interest": { - "description": "Interest accrued in USD (e.g. \"12.34\")", - "type": "string", - "example": "12.34" - }, - "liquidationLimit": { - "description": "LiquidationLimit is the collateral value threshold below which liquidation is triggered", - "type": "string", - "example": "900.00" - }, - "mHealthFactor": { - "description": "MHealthFactor is the maintenance health factor", - "type": "string", - "example": "1.10" - }, - "principal": { - "description": "Principal borrowed amount in USD (Debt − Interest)", - "type": "string", - "example": "737.91" - }, - "remainingCreditCapacity": { - "description": "RemainingCreditCapacity is the maximum credit available to the user taking into account debt and fixed fees.\nNote that this value is going to be the minimum of `remainingCreditCapacity(user)` and `immediateCreditCapacity` (see contracts).", - "type": "string", - "example": "1500.50" - }, - "totalCollateralValue": { - "description": "TotalCollateralValue is amount of deposited collateral value in token units displayed in highest denomination.", - "type": "string", - "example": "1000.00" - }, - "totalCreditCapacity": { - "description": "TotalCreditCapacity is the maximum credit available based on collateral in token units displayed in highest denomination.", - "type": "string", - "example": "1500.50" - } - } - }, - "credit.WrapResponse": { - "type": "object", - "required": [ - "amountOut", - "calls", - "tokenOut" - ], - "properties": { - "amountOut": { - "description": "Estimated shares minted", - "type": "string", - "example": "1000000000000000000" - }, - "calls": { - "description": "approve + deposit calls", - "type": "array", - "items": { - "$ref": "#/definitions/evm.ContractCall" - } - }, - "tokenOut": { - "description": "Vault share token received", - "type": "string", - "example": "0xeE8F4eC5672F09119b96Ab6fB59C27E1b7e44b61" - } - } - }, - "entity.ChainID": { - "type": "integer", - "format": "int32", - "enum": [ - 1, - 42161 - ], - "x-enum-varnames": [ - "Ethereum", - "Arbitrum" - ] - }, - "entity.Curator": { - "type": "string", - "enum": [ - "Gauntlet", - "Yo", - "Superform" - ], - "x-enum-varnames": [ - "Gauntlet", - "Yo", - "Superform" - ] - }, - "entity.EarnStrategy": { - "type": "string", - "enum": [ - "gauntlet-usdc-prime", - "yo-eth", - "yo-btc", - "yo-usdc", - "superform-usdc", - "" - ], - "x-enum-varnames": [ - "StrategyGauntletUSDCPrime", - "StrategyYoETH", - "StrategyYoBTC", - "StrategyYoUSDC", - "StrategySuperformUSDC", - "StrategyNone" - ] - }, - "entity.RiskScore": { - "type": "string", - "enum": [ - "1", - "3", - "5", - "7", - "10" - ], - "x-enum-varnames": [ - "VeryLow", - "Low", - "Medium", - "High", - "VeryHigh" - ] - }, - "entity.Strategy": { - "type": "string", - "enum": [ - "morpho-v1", - "yo-protocol", - "superform" - ], - "x-enum-varnames": [ - "MorphoV1", - "YoProtocol", - "SuperformProtocol" - ] - }, - "entity.StrategyType": { - "type": "string", - "enum": [ - "Lending" - ], - "x-enum-varnames": [ - "Lending" - ] - }, - "entity.TokenSymbol": { - "type": "string", - "enum": [ - "usdc", - "usdt", - "frxusd", - "liquidusd", - "liquidreserve" - ], - "x-enum-varnames": [ - "TokenUSDC", - "TokenUSDT", - "TokenFrxUSD", - "TokenLiquidUSD", - "TokenLiquidReserve" - ] - }, - "entity.VaultType": { - "type": "string", - "enum": [ - "erc4626", - "erc7540" - ], - "x-enum-varnames": [ - "ERC4626", - "ERC7540" - ] - }, - "evm.ContractCall": { - "type": "object", - "required": [ - "chain", - "data", - "to", - "value" - ], - "properties": { - "chain": { - "type": "string" - }, - "data": { - "type": "array", - "items": { - "type": "integer" - } - }, - "to": { - "type": "array", - "items": { - "type": "integer" - } - }, - "value": { - "$ref": "#/definitions/types.BigInt" - } - } - }, - "liquidity.BorrowCost": { - "description": "Borrow authorisation signature and details.", - "type": "object", - "required": [ - "borrowAmount", - "borrowCost", - "borrowToken", - "liquidityPool", - "nonce", - "signature" - ], - "properties": { - "borrowAmount": { - "description": "amount to be borrowed in lowest denomination of the borrowed token", - "type": "string" - }, - "borrowCost": { - "description": "cost to borrow the liquidity in lowest denomination of the borrowed token (excluding gas costs)", - "type": "string" - }, - "borrowToken": { - "description": "address of the token being borrowed from the liquidity pool", - "type": "string" - }, - "deadline": { - "description": "deadline for executing the borrow transaction", - "type": "string" - }, - "liquidityPool": { - "description": "address of the liquidity pool from which the liquidity will be borrowed", - "type": "string" - }, - "nonce": { - "description": "unique nonce for the borrow request", - "type": "string" - }, - "signature": { - "description": "hex string containing the MPC set signature used on the Liquidity pool contract", - "type": "string" - } - } - }, - "liquidity.BorrowSignatureResponse": { - "type": "object", - "required": [ - "data" - ], - "properties": { - "data": { - "$ref": "#/definitions/liquidity.BorrowCost" - } - } - }, - "liquidity.BorrowSignatureV2.body": { - "type": "object", - "required": [ - "caller", - "input", - "quoteId", - "txHash" - ], - "properties": { - "caller": { - "description": "eoa wallet address which will be used to call the liquidity pool contract", - "type": "string" - }, - "input": { - "description": "hex encoded input data which will be executed on the liquidity pool contract with borrowed liquidity", - "type": "string" - }, - "metadata": { - "description": "protocol-specific metadata as JSON object. For lifi-escrow: {\"srcChain\": \"eip155:1\"}\nwhere srcChain is the source chain CAIP ID used for on-chain order fetching fallback", - "type": "array", - "items": { - "type": "integer" - } - }, - "quoteId": { - "description": "quote ID obtained from the borrow quote endpoint", - "type": "string" - }, - "txHash": { - "description": "tx hash of the deposit transaction which will be used to verify liquidity repayment guarantee", - "type": "string" - } - } - }, - "liquidity.FeesResponse": { - "type": "object", - "required": [ - "data" - ], - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/definitions/types.FeeTier" - } - } - } - }, - "liquidity.GetStashSupportedTokensHandler.response": { - "type": "object", - "required": [ - "data" - ], - "properties": { - "data": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/config.Token" - } - } - } - }, - "liquidity.Quote": { - "type": "object", - "required": [ - "borrowCost", - "duration", - "estimatedFillDuration", - "feeBps", - "liquidityPool", - "quoteDuration", - "repaymentChain", - "repaymentRecipient", - "requiredInput", - "requiredOutput" - ], - "properties": { - "borrowCost": { - "description": "Cost to borrow the liquidity (in the smallest denomination). Excludes gas costs.", - "type": "string" - }, - "duration": { - "description": "Deprecated: use EstimatedFillDuration instead.", - "type": "number" - }, - "estimatedFillDuration": { - "description": "Estimated duration for the borrow transaction to complete.\nDepends on the required amount of confirmations on the source chain.", - "type": "number" - }, - "feeBps": { - "description": "Borrow fee in basis points. Excludes gas costs.", - "type": "number" - }, - "id": { - "description": "Unique identifier for the quote. Guarantees liquidity reservation. Used on borrow signature request.", - "type": "string" - }, - "liquidityPool": { - "description": "Liquidity pool from which the liquidity will be borrowed", - "type": "string" - }, - "quoteDuration": { - "description": "Duration for which this quote remains valid.", - "type": "number" - }, - "repaymentChain": { - "description": "Chain on which the repayment will be received", - "allOf": [ - { - "$ref": "#/definitions/entity.ChainID" - } - ] - }, - "repaymentRecipient": { - "description": "Address to which the repayment should be sent", - "type": "string" - }, - "requiredInput": { - "description": "Amount of input tokens required to fulfill the borrow (in the smallest denomination)", - "type": "string" - }, - "requiredOutput": { - "description": "Amount of output tokens that will be received from the borrow (in the smallest denomination)", - "type": "string" - } - } - }, - "liquidity.Unlock": { - "description": "unlock authorisation signature.", - "type": "object", - "required": [ - "signature" - ], - "properties": { - "signature": { - "type": "string" - } - } - }, - "liquidity.UnlockResponse": { - "type": "object", - "required": [ - "data" - ], - "properties": { - "data": { - "$ref": "#/definitions/liquidity.Unlock" - } - } - }, - "liquidity.availableLiquidityResponse": { - "type": "object", - "required": [ - "data" - ], - "properties": { - "data": { - "$ref": "#/definitions/liquidity.poolLiquidity" - } - } - }, - "liquidity.borrowQuoteResponse": { - "type": "object", - "required": [ - "data" - ], - "properties": { - "data": { - "$ref": "#/definitions/liquidity.Quote" - } - } - }, - "liquidity.poolLiquidity": { - "type": "object", - "required": [ - "address", - "balance" - ], - "properties": { - "address": { - "type": "string" - }, - "balance": { - "type": "string" - } - } - }, - "responses.ErrorResponse": { - "type": "object", - "required": [ - "error" - ], - "properties": { - "debug": { - "type": "string" - }, - "error": { - "type": "string" - } - } - }, - "server.GetSolverHandler.response": { - "type": "object", - "required": [ - "duration", - "solver" - ], - "properties": { - "duration": { - "type": "integer" - }, - "solver": { - "type": "string" - } - } - }, - "server.HealthHandler.response": { - "type": "object", - "required": [ - "status" - ], - "properties": { - "status": { - "type": "string" - } - } - }, - "types.BigInt": { - "type": "object" - }, - "types.FeeTier": { - "type": "object", - "required": [ - "feeBps", - "maxAmount", - "minAmount" - ], - "properties": { - "feeBps": { - "type": "number" - }, - "maxAmount": { - "type": "integer" - }, - "minAmount": { - "type": "integer" - } - } - } - } -} \ No newline at end of file diff --git a/api-reference/stash/liquidity/get-signing-authorization-for-a-liquidity-transaction.mdx b/api-reference/stash/liquidity/get-signing-authorization-for-a-liquidity-transaction.mdx deleted file mode 100644 index b05b5051..00000000 --- a/api-reference/stash/liquidity/get-signing-authorization-for-a-liquidity-transaction.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "Get Signing Authorization" -sidebarTitle: "Get Signing Authorization" -openapi: get /liquidity/chain/{chainId}/protocol/{protocol}/deposit/{txHash}/request ---- - - -```bash cURL -curl --request GET \ - --url 'https://api.sprinter.tech/liquidity/chain/{chainId}/protocol/{protocol}/deposit/{txHash}/request' -``` - -```python Python -import requests - -response = requests.get("https://api.sprinter.tech/liquidity/chain/{chainId}/protocol/{protocol}/deposit/{txHash}/request") -print(response.json()) -``` - -```javascript JavaScript -const response = await fetch( - "https://api.sprinter.tech/liquidity/chain/{chainId}/protocol/{protocol}/deposit/{txHash}/request" -); -const data = await response.json(); -console.log(data); -``` - -```go Go -package main - -import ( - "fmt" - "io" - "net/http" -) - -func main() { - resp, _ := http.Get("https://api.sprinter.tech/liquidity/chain/{chainId}/protocol/{protocol}/deposit/{txHash}/request") - defer resp.Body.Close() - body, _ := io.ReadAll(resp.Body) - fmt.Println(string(body)) -} -``` - \ No newline at end of file diff --git a/api-reference/stash/liquidity/get-the-borrow-quote-for-a-liquidity-transaction.mdx b/api-reference/stash/liquidity/get-the-borrow-quote-for-a-liquidity-transaction.mdx deleted file mode 100644 index 7c049751..00000000 --- a/api-reference/stash/liquidity/get-the-borrow-quote-for-a-liquidity-transaction.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "Get Borrow Quote" -sidebarTitle: "Get Borrow Quote" -openapi: get /liquidity/chain/{chain}/protocol/{protocol}/type/{type}/quote ---- - - -```bash cURL -curl --request GET \ - --url 'https://api.sprinter.tech/liquidity/chain/{chain}/protocol/{protocol}/type/{type}/quote' -``` - -```python Python -import requests - -response = requests.get("https://api.sprinter.tech/liquidity/chain/{chain}/protocol/{protocol}/type/{type}/quote") -print(response.json()) -``` - -```javascript JavaScript -const response = await fetch( - "https://api.sprinter.tech/liquidity/chain/{chain}/protocol/{protocol}/type/{type}/quote" -); -const data = await response.json(); -console.log(data); -``` - -```go Go -package main - -import ( - "fmt" - "io" - "net/http" -) - -func main() { - resp, _ := http.Get("https://api.sprinter.tech/liquidity/chain/{chain}/protocol/{protocol}/type/{type}/quote") - defer resp.Body.Close() - body, _ := io.ReadAll(resp.Body) - fmt.Println(string(body)) -} -``` - \ No newline at end of file diff --git a/api-reference/stash/openapi.json b/api-reference/stash/openapi.json deleted file mode 100644 index 3cf1a456..00000000 --- a/api-reference/stash/openapi.json +++ /dev/null @@ -1,269 +0,0 @@ -{ - "openapi": "3.0.0", - "info": { - "title": "Sprinter Stash API", - "version": "1.0.0", - "description": "Sprinter Stash V1 API for liquidity transactions." - }, - "servers": [ - { - "url": "https://api.sprinter.tech", - "description": "Production server" - } - ], - "paths": { - "/liquidity/chain/{chain}/protocol/{protocol}/type/{type}/quote": { - "get": { - "operationId": "getBorrowQuote", - "summary": "Get the borrow quote for a liquidity transaction", - "description": "Calculates the borrow quote including borrow cost, required input/output, and duration.", - "tags": ["Liquidity"], - "parameters": [ - { - "name": "chain", - "in": "path", - "required": true, - "description": "Source CAIP chain ID (e.g., eip155:1)", - "schema": { - "type": "string" - } - }, - { - "name": "protocol", - "in": "path", - "required": true, - "description": "Protocol name (e.g., Across)", - "schema": { - "type": "string" - } - }, - { - "name": "type", - "in": "path", - "required": true, - "description": "Quote algorithm type (e.g., ExactInput, ExactOutput)", - "schema": { - "type": "string" - } - }, - { - "name": "amount", - "in": "query", - "required": true, - "description": "Amount of tokens in smallest denomination (e.g., 49805421)", - "schema": { - "type": "string" - } - }, - { - "name": "token", - "in": "query", - "required": true, - "description": "Token address (hex, e.g., 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2)", - "schema": { - "type": "string" - } - }, - { - "name": "network", - "in": "query", - "required": true, - "description": "CAIP formatted network ID (e.g., eip155:1)", - "schema": { - "type": "string" - } - }, - { - "name": "exclusive_fill", - "in": "query", - "required": false, - "description": "Whether you have exclusivity to fill this quote", - "schema": { - "type": "boolean" - } - } - ], - "responses": { - "200": { - "description": "Successful borrow quote response", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "object", - "properties": { - "borrowCost": { - "type": "string" - }, - "duration": { - "type": "string" - }, - "liquidityPool": { - "type": "string" - }, - "repaymentChain": { - "type": "integer" - }, - "repaymentRecipient": { - "type": "string" - }, - "requiredInput": { - "type": "string" - }, - "requiredOutput": { - "type": "string" - } - } - } - } - } - } - } - }, - "400": { - "description": "Bad request", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "500": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/liquidity/chain/{chainId}/protocol/{protocol}/deposit/{txHash}/request": { - "get": { - "operationId": "getSigningAuthorization", - "summary": "Get signing authorization for a liquidity transaction", - "description": "Returns signed authorization for a liquidity transaction based on the deposit transaction hash.", - "tags": ["Liquidity"], - "parameters": [ - { - "name": "chainId", - "in": "path", - "required": true, - "description": "Destination chain CAIP ID (e.g., eip155:8453)", - "schema": { - "type": "string" - } - }, - { - "name": "protocol", - "in": "path", - "required": true, - "description": "Protocol name (e.g., Across)", - "schema": { - "type": "string" - } - }, - { - "name": "txHash", - "in": "path", - "required": true, - "description": "Transaction hash of the deposit", - "schema": { - "type": "string" - } - }, - { - "name": "Input", - "in": "query", - "required": true, - "description": "Input data (relay data)", - "schema": { - "type": "string" - } - }, - { - "name": "Caller", - "in": "query", - "required": true, - "description": "Caller address (solver address)", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "Successful signing authorization response", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "borrowAmount": { - "type": "string" - }, - "borrowCost": { - "type": "string" - }, - "liquidityPool": { - "type": "string" - }, - "nonce": { - "type": "string" - }, - "signature": { - "type": "string" - } - } - } - } - } - }, - "400": { - "description": "Bad request", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "500": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - } - }, - "components": { - "schemas": { - "ErrorResponse": { - "type": "object", - "properties": { - "error": { - "type": "string" - }, - "debug": { - "type": "string" - } - }, - "required": ["error"] - } - } - } -} diff --git a/architecture/stash-repayment.mdx b/architecture/stash-repayment.mdx deleted file mode 100644 index 679f7423..00000000 --- a/architecture/stash-repayment.mdx +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: "Stash Repayment Service" -description: "Automated cross-chain repayment and bridging worker" ---- - -The stash-repayment service is a long-running background worker that automates cross-chain loan repayment. It is **not** an API — it only exposes a `/metrics` endpoint for Prometheus. - -## Flow Overview - -Execution runs in two sequential phases per chain: - -### Phase 1: Repayment - -``` -unlock() → balance() → debt() → repay() -``` - -1. **unlock** — Unlock protocol-specific assets -2. **balance** — Get solver token balances -3. **debt** — Query outstanding debts per solver -4. **repay** — Repay using available funds (lower threshold if pool borrowing is paused) - -### Phase 2: Bridging - -``` -balance() → debt() → bridge() -``` - -1. **balance** — Check repayer contract balance -2. **debt** — Check updated solver debts -3. **bridge** — Generate and execute bridging transactions: - - Same-chain transfers prioritized - - Bridge amount = debt amount - - Surplus (profit) included in bridging txs - - Lower threshold if destination pool has borrowing paused - -## Bridge Providers - -| ID | Provider | -|----|----------| -| `0` | LOCAL (same-chain) | -| `1` | CCTP | -| `2` | ACROSS | -| `4` | EVERCLEAR | -| `254` | MAYAN | - -## External Dependencies - -| Service | Purpose | -|---------|---------| -| Sprinter API (`api.sprinter.tech`) | Stash debt/balance queries | -| LiFi | Token swaps | -| CoinMarketCap | Token pricing | -| CCTP / Across / Everclear / Mayan | Cross-chain bridging | - -## Key Configuration - -| Variable | Default | Description | -|----------|---------|-------------| -| `REPAYMENT_MINS` | `5` | Minutes between repayment cycles | -| `REPAYMENT_THRESHOLD` | `$100` | Min USD for repayment | -| `BRIDGING_MINS` | `60` | Minutes between bridging cycles | -| `BRIDGING_THRESHOLD` | `$0.10` | Min USD for bridging | -| `BRIDGING_MAX_FEE_PCT` | `5%` | Max acceptable bridge fee | -| `LIQUIDATION_MINS` | `5` | Minutes between liquidation checks | diff --git a/quickstart/kast-card.mdx b/quickstart/kast-card.mdx deleted file mode 100644 index 75a503b1..00000000 --- a/quickstart/kast-card.mdx +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: "Kast.xyz Integration" -description: "How Kast can add credit-backed card spending via the Sprinter Credit API — cardholders spend against locked collateral instead of prefunded balances" ---- - -## Overview - -[Kast](https://kast.xyz) is a stablecoin-powered neobank with Visa debit cards. Today, users deposit stablecoins to fund their card. With Sprinter Credit, Kast can offer **credit-backed spending** — cardholders lock collateral (which earns yield), and Kast draws USDC from Sprinter to settle card transactions. - -Kast keeps its existing stack — KYC, card issuance, settlement via Rain/Third National. Sprinter plugs in as the credit engine. - -| Without Sprinter | With Sprinter | -|---|---| -| User deposits USDC → card funded → user spends | User locks collateral → Kast draws credit on card use | -| Deposited assets sit idle | Collateral earns yield in DeFi vaults | -| User manually tops up balance | Credit line funds the card automatically | -| Single-chain deposits | Cross-chain collateral — one credit line | - -
-```mermaid -flowchart TD - A[Cardholder locks collateral] --> B[Credit line active — card spending enabled] - B --> C[Card swipe → Kast draws USDC via Sprinter] - C --> D[USDC delivered to Kast settlement address] - D --> E[Repay at end of billing cycle] - E --> F[Collateral unlocked] -``` -
- -## What Kast Keeps vs What Sprinter Adds - -| Kast handles (no changes) | Sprinter provides | -|---|---| -| KYC via Sumsub | Collateral locking & credit line activation | -| Card issuance (virtual + physical) | USDC credit draws to Kast's settlement address | -| Apple Pay / Google Pay | Health factor monitoring, LTV enforcement | -| Visa settlement via Rain / Third National | Earn vaults — collateral earns while locked | -| Cashback rewards (1–8% by tier) | Repayment & collateral unlock | - -## Before You Start - -Card programs that draw credit on behalf of cardholders (e.g. just-in-time at card swipe) need a delegation model. You should decide upfront: - -1. **Which account type?** EOA (existing wallet) or Smart Account — this affects onboarding and how delegation is set up. See [Credit Accounts](/sprinter-credit/credit-accounts). -2. **Which operator model?** A [Credit Operator](/sprinter-credit/policy-engine#credit-operators) lets your backend draw credit without cardholder interaction. Most card programs use the `ExclusiveOperator` — see [Delegated Credit Draws](#delegated-credit-draws) below for implementation. - -## Integration - - - - After Kast's normal onboarding, the cardholder locks collateral to activate credit-backed spending. Optionally wrap into an earn vault so collateral earns yield while locked. - - ```bash - # Lock USDC as collateral on Base - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/lock?amount=1000000000&asset=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' - - # Or lock + earn vault (collateral earns yield) - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/lock?amount=1000000000&asset=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913&earn=STRATEGY_ID' - ``` - - Returns `{ calls: ContractCall[] }` — execute in the cardholder's wallet. Once locked, the credit line is active. - - Use `GET /credit/protocol` to fetch available collateral assets and earn strategies. - - - - Query the cardholder's credit position. Map `remainingCreditCapacity` to the Kast card spending limit. - - ```bash - curl -X GET https://api.sprinter.tech/credit/accounts/0xUSER/info - ``` - - ```json - { - "data": { - "USDC": { - "totalCreditCapacity": "900.00", - "remainingCreditCapacity": "900.00", - "totalCollateralValue": "1000.00", - "principal": "0", - "interest": "0", - "healthFactor": "Infinity", - "dueDate": null - } - } - } - ``` - - Poll periodically to update the limit as collateral values or debt change. - - - - When the card is used, Kast draws USDC from the cardholder's credit line to its settlement address. Two funding models: - - - Just-in-time draws require a delegation model (Operator or Smart Account). If you haven't set this up yet, see [Before You Start](#before-you-start). - - - - - Draw at the moment of each Visa authorization. Kast's backend receives the auth from Rain/Third National, calls Sprinter `/draw`, executes on-chain, and responds — all within ~2 seconds. - - ```bash - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/draw?amount=50000000&receiver=0xKAST_SETTLEMENT_ADDRESS' - ``` - - This requires a [delegated signer](#delegated-credit-draws) authorized to execute on behalf of the cardholder. See the [Authorization Webhook Handler](/quickstart/kast-card/authorization-webhook) for a complete implementation. - - - Draw a lump sum to the cardholder's Kast deposit address before they spend. Simpler — no real-time on-chain execution needed. - - ```bash - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/draw?amount=500000000&receiver=0xKAST_DEPOSIT_ADDRESS' - ``` - - Kast auto-detects the USDC deposit and credits the card balance (typically 1–5 minutes). - - - - | Parameter | Description | - |---|---| - | `account` | Cardholder's wallet address | - | `amount` | USDC amount (6 decimals — $50 = `50000000`) | - | `receiver` | Kast's settlement address or per-user deposit address | - - Returns `{ calls: ContractCall[] }` — execute on-chain to deliver USDC. - - - A **0.50% origination fee** is deducted from each draw. See [Fees](/sprinter-credit/credit-engine#fees). - - - - - At end of billing cycle, repay the cardholder's outstanding debt. Once cleared, collateral can be unlocked. - - ```bash - # Check outstanding debt - curl -X GET https://api.sprinter.tech/credit/accounts/0xUSER/info - - # Repay (anyone can repay on behalf of any account) - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/repay?amount=50000000' - - # Unlock collateral - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/unlock?amount=1000000000&asset=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' - ``` - - Credit runs on a 30-day billing cycle with a 7-day grace period. See [Fees](/sprinter-credit/credit-engine#fees). - - - -## Delegated Credit Draws - -Just-in-time card authorizations require drawing credit without cardholder interaction. This requires a [Credit Operator](/sprinter-credit/policy-engine#credit-operators) — a contract that lets your backend act on the user's credit position without custody. See [Credit Accounts](/sprinter-credit/credit-accounts) for choosing between EOA + Operator vs Smart Account. Two approaches: - - - - Kast deploys an [`ExclusiveOperator`](https://github.com/sprintertech/remote-collateral-contracts/blob/main/contracts/operator/ExclusiveOperator.sol) contract. Kast's backend address is the authorized caller. Cardholders opt in by setting the operator on their credit position. - - **Setup:** - 1. Deploy `ExclusiveOperator` with Kast's backend as the `caller` - 2. Cardholder calls `setOperator()` on the Credit Hub - 3. Cardholder calls `addCreditReceiver()` to whitelist Kast's settlement address - - **At swipe time:** - ```solidity - // Kast backend calls directly — no cardholder signature needed - operator.openCreditLine(borrower, kastSettlementAddress, amount); - ``` - - **Safety:** The operator can only draw to whitelisted receivers — never touch collateral. Revocation has a time delay to prevent abuse during active billing cycles. - - - Cardholders deploy a smart account (ERC-4337) and configure a session key authorizing Kast's backend to call `/draw`. Cardholder retains full custody. - - Most trust-minimized option — but requires cardholders to use smart accounts. - - - - - Complete TypeScript implementation showing how to wire Sprinter `/draw` into Kast's Visa authorization flow — signature validation, credit checks, on-chain execution, all within the ~2 second window. - - -## Integration Notes - - - - Kast supports deposits on Ethereum, Solana, Polygon, Arbitrum, and Base (via Rain). Sprinter Credit operates on Base — use Base for settlement or deposit addresses. - - - Cardholders earn on both sides — vault yield on locked collateral (via Sprinter earn strategies) and 1–8% cashback on spend (via Kast card tiers). This makes credit-backed spending strictly better than prefunded deposits. - - - Poll `healthFactor` from the info endpoint and adjust card spending limits accordingly. A health factor approaching 1.0 means the position is close to liquidation — reduce or freeze the card limit. See [Risk Management](/sprinter-credit/risk-management). - - - Always decline if the draw cannot be confirmed on-chain. A declined transaction is recoverable; an unauthorized spend is not. - - - The signing key that executes JIT draws must be secured with HSM or cloud KMS (AWS KMS, GCP Cloud KMS). Never store it in environment variables on shared infrastructure. - - - -## API Reference - -Every step maps to a single Sprinter endpoint: - -| Kast Card Flow | Sprinter API | -|---|---| -| Cardholder locks collateral | `GET /credit/accounts/{account}/lock` | -| Lock + earn vault | `GET /credit/accounts/{account}/lock?earn=STRATEGY_ID` | -| Check spending limit | `GET /credit/accounts/{account}/info` | -| Draw USDC to settlement | `GET /credit/accounts/{account}/draw?receiver={addr}` | -| Repay debt | `GET /credit/accounts/{account}/repay` | -| Unlock collateral | `GET /credit/accounts/{account}/unlock` | -| Get protocol config | `GET /credit/protocol` | - -## Try It - -The **Card Program Demo** runs the full credit-backed card lifecycle on Base — collateral locking, credit draw to a settlement address, repay, and unlock — with a mock card issuer that simulates the card program side. - - - Clone the repo, add a wallet with USDC and ETH on Base, and run `npm run dev`. The mock card issuer handles the card program side — focus on the Sprinter Credit steps. - - -## Related - - - - Generic card program integration — works with any issuer. - - - Health factor, LTVs, and liquidation mechanics. - - - Full API reference with interactive playground. - - diff --git a/quickstart/kast-card/authorization-webhook.mdx b/quickstart/kast-card/authorization-webhook.mdx deleted file mode 100644 index 5a6f39a1..00000000 --- a/quickstart/kast-card/authorization-webhook.mdx +++ /dev/null @@ -1,259 +0,0 @@ ---- -title: "Kast Authorization Webhook" -description: "TypeScript implementation for handling Kast Visa card authorization webhooks with JIT credit draws via the Sprinter Credit API" ---- - -## Overview - -When a Kast cardholder swipes their Visa card, Third National (the card issuer) sends an authorization request to your backend. You have ~2 seconds to check credit, execute an on-chain draw, and respond. - -``` -Card swipe → Visa → Third National → Kast backend → Your webhook endpoint - ├─ Validate signature - ├─ Look up wallet from card ID - ├─ GET /credit/accounts/{account}/info → check credit - ├─ GET /credit/accounts/{account}/draw → build draw calldata - ├─ Execute on-chain via delegated signer - └─ Respond: approved / declined -``` - - -This example assumes a webhook-based authorization flow from Kast/Third National. Adapt signature validation and response format to match the actual integration spec when available. - - -## Implementation - - - - ```typescript - import express from "express"; - import crypto from "crypto"; - import { ethers } from "ethers"; - - const app = express(); - app.use(express.json({ verify: (req: any, _res, buf) => { req.rawBody = buf; } })); - - const SPRINTER_API = "https://api.sprinter.tech"; - const KAST_WEBHOOK_SECRET = process.env.KAST_WEBHOOK_SECRET!; - const SETTLEMENT_ADDRESS = process.env.SETTLEMENT_ADDRESS!; // Third National settlement - const RPC_URL = process.env.RPC_URL!; // Base RPC - const SIGNER_PRIVATE_KEY = process.env.SIGNER_PRIVATE_KEY!; - - const provider = new ethers.JsonRpcProvider(RPC_URL); - const signer = new ethers.Wallet(SIGNER_PRIVATE_KEY, provider); - ``` - - - - ```typescript - interface ContractCall { - to: string; - data: string; - value: string; - } - - interface CreditInfo { - data: { - USDC: { - totalCreditCapacity: string; - remainingCreditCapacity: string; - totalCollateralValue: string; - principal: string; - interest: string; - healthFactor: string; - dueDate: string | null; - }; - }; - } - - // Use Redis or a database in production - const processed = new Map(); - - function validateSignature(rawBody: Buffer, signature: string): boolean { - const expected = crypto - .createHmac("sha256", KAST_WEBHOOK_SECRET) - .update(rawBody) - .digest("hex"); - return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected)); - } - - async function getWalletForCard(cardId: string): Promise { - // TODO: query your database mapping Kast card IDs to wallet addresses - throw new Error(`Implement getWalletForCard for cardId: ${cardId}`); - } - - async function getCreditInfo(account: string): Promise { - const res = await fetch(`${SPRINTER_API}/credit/accounts/${account}/info`); - if (!res.ok) throw new Error(`Credit info failed: ${res.status}`); - return res.json(); - } - - async function buildDrawCalls( - account: string, - amountUsdc: string, - receiver: string - ): Promise { - const url = new URL(`${SPRINTER_API}/credit/accounts/${account}/draw`); - url.searchParams.set("amount", amountUsdc); - url.searchParams.set("receiver", receiver); - const res = await fetch(url.toString()); - if (!res.ok) throw new Error(`Draw calldata failed: ${res.status}`); - const data = await res.json(); - return data.calls; - } - - async function executeCalls(calls: ContractCall[]): Promise { - let lastTxHash = ""; - for (const call of calls) { - const tx = await signer.sendTransaction({ - to: call.to, - data: call.data, - value: call.value || "0", - }); - const receipt = await tx.wait(); - if (!receipt || receipt.status !== 1) { - throw new Error(`Transaction reverted: ${tx.hash}`); - } - lastTxHash = tx.hash; - } - return lastTxHash; - } - - /** $1.00 = 100 cents = 1_000_000 USDC units (6 decimals) */ - function centsToUsdcUnits(cents: number): string { - return (cents * 10_000).toString(); - } - ``` - - - - ```typescript - app.post("/webhooks/kast/authorization", async (req, res) => { - try { - // 1. Validate webhook signature - const signature = req.headers["x-kast-signature"] as string; - if (!signature || !validateSignature((req as any).rawBody, signature)) { - return res.status(401).json({ error: "Invalid signature" }); - } - - const { id, cardId, amount, currency, merchantName } = req.body; - - // 2. Idempotency — return cached result if already processed - const cached = processed.get(id); - if (cached) return res.json(cached); - - // 3. Look up user wallet from Kast card ID - const wallet = await getWalletForCard(cardId); - if (!wallet) { - processed.set(id, { approved: false }); - return res.json({ approved: false, reason: "unknown_card" }); - } - - // 4. Convert amount to USDC (Kast supports USD, apply FX if non-USD) - const usdcAmount = currency === "USD" - ? centsToUsdcUnits(amount) - : centsToUsdcUnits(amount); // TODO: apply FX rate for non-USD - - // 5. Check available credit and health factor - const info = await getCreditInfo(wallet); - const remaining = parseFloat(info.data.USDC.remainingCreditCapacity); - const healthFactor = parseFloat(info.data.USDC.healthFactor); - const requestedUsd = amount / 100; - - if (requestedUsd > remaining) { - processed.set(id, { approved: false }); - return res.json({ approved: false, reason: "insufficient_credit" }); - } - - if (healthFactor < 1.3) { - processed.set(id, { approved: false }); - return res.json({ approved: false, reason: "low_health_factor" }); - } - - // 6. Build and execute the credit draw - const calls = await buildDrawCalls(wallet, usdcAmount, SETTLEMENT_ADDRESS); - const txHash = await executeCalls(calls); - - console.log(`Approved: ${merchantName} $${requestedUsd} for card ${cardId} tx:${txHash}`); - processed.set(id, { approved: true, txHash }); - return res.json({ approved: true, txHash }); - } catch (error) { - // Fail closed — always decline on error - console.error("Authorization error:", error); - return res.json({ approved: false, reason: "internal_error" }); - } - }); - - app.listen(3001, () => console.log("Kast webhook handler running on :3001")); - ``` - - - -## Delegated Signing - -Card authorizations must complete without user interaction. Your backend needs a server-side signer authorized to draw credit on the user's behalf. - - - - User grants a scoped session key that can only call the credit draw function. - - - User pre-signs EIP-2612 permits for USDC transfers. - - - User's smart wallet delegates draw authority to your backend EOA. - - - - -The delegated signer can draw credit from user accounts. Secure the private key with HSM or KMS in production — never store it in environment variables on shared infrastructure. - - -## Latency Budget - -Visa expects a response within ~2 seconds: - -| Step | Target | Notes | -|---|:---:|---| -| Signature validation | < 1ms | Local crypto | -| Database lookup (card → wallet) | < 10ms | Index on Kast card ID | -| `GET /credit/accounts/{account}/info` | < 100ms | Sprinter API | -| `GET /credit/accounts/{account}/draw` | < 100ms | Sprinter API | -| On-chain execution | < 1000ms | Dedicated Base RPC node | -| **Total** | **< 1300ms** | ~700ms buffer | - - -Use a dedicated RPC node on Base. Public endpoints will exceed the time budget under load. - - -## Production Checklist - - - - - [ ] Replace in-memory idempotency map with Redis or database - - [ ] Use a dedicated Base RPC node (Alchemy, QuickNode, or self-hosted) - - [ ] Store signer key in HSM or cloud KMS (AWS KMS, GCP Cloud KMS) - - [ ] Set up webhook endpoint behind a load balancer with TLS - - - - [ ] Implement `getWalletForCard()` mapping Kast card IDs to user wallets - - [ ] Confirm settlement address with Third National - - [ ] Handle FX conversion for non-USD transactions (Kast charges 2% FX fee) - - [ ] Map Kast card tiers (Standard/Premium/Luxe) to Sprinter credit configurations - - - - [ ] Monitor authorization latency (p99 < 2s) - - [ ] Alert on elevated decline rates - - [ ] Track on-chain execution success rate - - [ ] Monitor health factors across all active Kast cardholders - - - -## Environment Variables - -| Variable | Description | -|---|---| -| `KAST_WEBHOOK_SECRET` | Webhook signing secret from Kast/Third National | -| `SETTLEMENT_ADDRESS` | Third National's USDC settlement address on Base | -| `RPC_URL` | Base RPC endpoint (dedicated node recommended) | -| `SIGNER_PRIVATE_KEY` | Delegated signer private key (HSM/KMS in production) | diff --git a/quickstart/metamask-integration.mdx b/quickstart/metamask-integration.mdx deleted file mode 100644 index 9c747259..00000000 --- a/quickstart/metamask-integration.mdx +++ /dev/null @@ -1,276 +0,0 @@ ---- -title: "MetaMask Integration" -description: "Let MetaMask users borrow against their existing ETH and stETH — no selling, no bridging, just credit" ---- - -## Overview - -With Sprinter Credit, MetaMask users can borrow USDC against their existing holdings — ETH, stETH, wstETH — without selling. Users lock collateral, get a credit line, and spend or transfer USDC while their assets stay productive. - -MetaMask already has the signer. Sprinter provides the credit engine — you just execute the calldata it returns. - -| Without Sprinter | With Sprinter | -|---|---| -| User sells ETH to get USDC | User locks ETH, draws USDC — keeps ETH exposure | -| stETH sits in wallet earning yield but illiquid | stETH earns yield **and** backs a spendable credit line | -| User bridges to get stablecoins on another chain | Cross-chain collateral — one credit line, any chain | -| No spending power without selling | Instant USDC credit against existing portfolio | - -
-```mermaid -flowchart TD - A[User locks ETH / stETH as collateral] --> B[Credit line activated] - B --> C[User draws USDC from credit line] - C --> D[USDC sent to any address — pay, transfer, swap] - D --> E[User repays when ready] - E --> F[Collateral unlocked — ETH / stETH returned] -``` -
- -Every Sprinter endpoint returns `{ calls: ContractCall[] }` — unsigned transaction calldata. MetaMask signs and submits. No custody handoff. - -## What You Need from Sprinter - -| MetaMask handles | Sprinter handles | -|---|---| -| Wallet UX, account management | Collateral locking & credit line activation | -| Transaction signing & submission | USDC credit draws to any receiver address | -| Portfolio display, balance tracking | Health factor monitoring, LTV enforcement | -| Network switching, gas estimation | Earn vaults (collateral earns yield while locked) | -| User authentication | Repayment & collateral unlock | - -## Supported Collateral - -Users can lock assets they already hold. Each asset has its own LTV based on its risk profile: - -| Asset | LTV | Collateral Tier | Notes | -|---|:---:|---|---| -| ETH | 80% | Raw volatile | Native ETH — highest liquidity | -| stETH | 75% | Volatile DEX-swap | Lido staked ETH — earns staking yield while locked | -| wstETH | 75% | Volatile DEX-swap | Wrapped stETH — same yield, no rebase | -| USDC | 90% | Raw stablecoin | Stablecoin — highest LTV | - -Use `GET /credit/protocol` to fetch the latest supported assets and LTVs. See [Supported Assets](/sprinter-credit/supported-assets) for the full list and collateral tier framework. - -## Before You Start - -For most wallet integrations, users sign every transaction themselves — no delegation needed. A standard EOA (existing wallet) works out of the box. - -If you want to support features like auto-repayment, scheduled draws, or agent-assisted actions, you'll need a delegation model. See [Credit Accounts](/sprinter-credit/credit-accounts) for EOA + Operator vs Smart Account trade-offs, and [Credit Operators](/sprinter-credit/policy-engine#credit-operators) for how delegation works. - -## Integration - - - - When a user wants to borrow, they lock collateral from their wallet. The API returns calldata — MetaMask signs and submits. - - - - ```bash - # Lock 1 ETH as collateral on Base - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/lock?amount=1000000000000000000&asset=0xETH_ADDRESS' - ``` - - - ```bash - # Lock stETH as collateral - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/lock?amount=1000000000000000000&asset=0xSTETH_ADDRESS' - ``` - - - ```bash - # Lock collateral and wrap into a yield-bearing vault - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/lock?amount=1000000000000000000&asset=0xCOLLATERAL&earn=STRATEGY_ID' - ``` - The `earn` parameter wraps the asset into a yield-bearing vault — collateral earns while the credit line is active. Use `GET /credit/protocol` for available strategies. - - - - Returns `{ calls: ContractCall[] }` — present to the user for signing. Once confirmed, the credit line is active. - - - - After locking, display the user's credit position in the MetaMask UI. - - ```bash - curl -X GET https://api.sprinter.tech/credit/accounts/0xUSER/info - ``` - - ```json - { - "data": { - "USDC": { - "totalCreditCapacity": "2400.00", - "remainingCreditCapacity": "2400.00", - "totalCollateralValue": "3000.00", - "principal": "0", - "interest": "0", - "healthFactor": "Infinity", - "dueDate": null - } - } - } - ``` - - Key fields to surface in your UI: - - | Field | What to show | - |---|---| - | `remainingCreditCapacity` | Available to borrow | - | `totalCollateralValue` | Total locked collateral value | - | `principal` + `interest` | Outstanding debt | - | `healthFactor` | Position health (warn below 1.5, danger below 1.2) | - | `dueDate` | Repayment deadline | - - - - When the user wants to borrow, draw USDC to any address — their own wallet, a merchant, a DEX, another wallet. - - ```bash - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/draw?amount=500000000&receiver=0xRECEIVER' - ``` - - | Parameter | Description | - |---|---| - | `account` | User's wallet address (borrower) | - | `amount` | USDC amount (6 decimals — $500 = `500000000`) | - | `receiver` | Any address — user's wallet, merchant, protocol | - - Returns `{ calls: ContractCall[] }` — user signs, USDC is delivered. - - - A **0.50% origination fee** is deducted from each draw. See [Fees](/sprinter-credit/credit-engine#fees). - - - - - Users repay debt to free their collateral. Anyone can repay on behalf of any account. - - ```bash - # Check outstanding debt - curl -X GET https://api.sprinter.tech/credit/accounts/0xUSER/info - - # Repay - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/repay?amount=500000000' - - # Unlock collateral - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/unlock?amount=1000000000000000000&asset=0xCOLLATERAL' - ``` - - Credit runs on a 30-day billing cycle with a 7-day grace period. See [Fees](/sprinter-credit/credit-engine#fees). - - - -## UX Patterns - - - - If MetaMask supports in-app payments, Sprinter Credit lets users pay with USDC drawn against their ETH/stETH — no selling required. - - **Flow:** - 1. User initiates a payment within MetaMask - 2. MetaMask checks if the user has a Sprinter credit line with sufficient capacity - 3. If yes — draw USDC to the merchant/recipient via `/draw` - 4. User signs one transaction (the draw), payment is settled - 5. User repays later from any source - - **What happens after draw:** USDC lands directly in the merchant's or recipient's wallet. The payment is settled on-chain — no intermediary, no delay. The user paid with credit backed by their ETH, and the merchant received real USDC. - - This turns every ETH/stETH holder into a USDC spender without any sell pressure. - - - Display Sprinter Credit as a feature within MetaMask's portfolio view. - - **UX:** - - Show "Available Credit" alongside token balances - - "Borrow" button next to eligible collateral (ETH, stETH) - - Health factor gauge with color coding (green → yellow → red) - - Repayment reminder before due date - - **What happens after draw:** When the user draws, USDC arrives in their wallet instantly — ready to send, swap, or spend. It feels like unlocking liquidity that was always there, just locked up in ETH. - - Users treat it like an overdraft — they see available credit and draw when needed. - - - When a user tries to swap or purchase but lacks stablecoins, offer credit as an alternative to selling. - - **Flow:** - 1. User wants to buy an NFT / swap for a token but has no USDC - 2. Prompt: "Borrow $X against your ETH instead of selling?" - 3. User confirms → lock ETH, draw USDC, complete purchase - 4. User repays within 30 days - - **What happens after draw:** The USDC goes directly to the seller or protocol — the NFT lands in the user's wallet, the swap executes, the purchase completes. The user got what they wanted without selling a single asset. They repay on their own schedule. - - This prevents forced selling and keeps users' long positions intact. - - - Users can send USDC to friends, family, or other wallets — funded by their credit line instead of their token balance. - - **Flow:** - 1. User wants to send $200 to a friend but only holds ETH - 2. User draws USDC with the friend's address as the `receiver` - 3. USDC arrives in the friend's wallet — one transaction - - **What happens after draw:** The friend receives USDC directly — no intermediate step, no swap. The sender's ETH stays locked and earning yield. This makes credit-backed transfers as simple as a regular wallet send. - - - Let users interact with DeFi protocols using borrowed USDC — provide liquidity, enter yield positions, or fund a DEX trade. - - **Flow:** - 1. User wants to provide liquidity on a DEX but doesn't want to sell ETH for the USDC side - 2. User draws USDC from their credit line - 3. USDC is used to enter the LP position alongside their existing tokens - - **What happens after draw:** The drawn USDC goes to the user's wallet or directly to a protocol address. The user is now earning LP fees on borrowed USDC while their ETH collateral continues earning staking yield — yield on both sides. - - - -## Integration Notes - - - - Poll `healthFactor` from the info endpoint and surface alerts in your wallet UI. A health factor approaching 1.0 means the position is close to liquidation — prompt the user to add collateral or repay. See [Risk Management](/sprinter-credit/risk-management). - - - Use the `earn` parameter when locking to wrap collateral into a yield-bearing vault. For stETH users, this means earning staking yield **and** vault yield simultaneously. Use `GET /credit/protocol` to discover available strategies. - - - Sprinter returns unsigned calldata — the user's wallet signs everything. Sprinter never has access to user funds. This means your wallet integration doesn't change your custody model. - - - If your users sign every transaction themselves, a standard EOA (existing wallet) is all you need. If you want to enable delegated actions like auto-repayment or scheduled draws, you'll need to choose between an Operator contract or Smart Account. See [Credit Accounts](/sprinter-credit/credit-accounts) for the full comparison. - - - ETH and stETH prices fluctuate. If collateral value drops, the health factor decreases and the user may face liquidation. Build alerts into your wallet UI — warn at health factor 1.5, strongly warn at 1.2. - - - Users can lock collateral on any supported chain. Sprinter handles cross-chain accounting — one credit line across all chains. This means users don't need to bridge assets before borrowing. - - - -## API Reference - -Every step maps to a single Sprinter endpoint: - -| Wallet Flow | Sprinter API | -|---|---| -| User locks collateral | `GET /credit/accounts/{account}/lock` | -| Lock + earn vault | `GET /credit/accounts/{account}/lock?earn=STRATEGY_ID` | -| Show credit position | `GET /credit/accounts/{account}/info` | -| Draw USDC | `GET /credit/accounts/{account}/draw?receiver={addr}` | -| Repay debt | `GET /credit/accounts/{account}/repay` | -| Unlock collateral | `GET /credit/accounts/{account}/unlock` | -| Get protocol config | `GET /credit/protocol` | - - - - Core credit draw lifecycle — lock, draw, repay, unlock. - - - Full collateral list, LTVs, and earn strategies. - - - Full API reference with interactive playground. - - diff --git a/quickstart/wallet-integration.mdx b/quickstart/wallet-integration.mdx deleted file mode 100644 index b7e75855..00000000 --- a/quickstart/wallet-integration.mdx +++ /dev/null @@ -1,276 +0,0 @@ ---- -title: "Wallet Integration" -description: "Let wallet users borrow against their existing ETH and stETH — no selling, no bridging, just credit" ---- - -## Overview - -If you run a wallet or super app (WalletConnect, MetaMask, Rainbow, etc.), Sprinter Credit lets your users borrow USDC against their existing holdings — ETH, stETH, wstETH — without selling. Users lock collateral, get a credit line, and spend or transfer USDC while their assets stay productive. - -Your wallet already has the signer. Sprinter provides the credit engine — you just execute the calldata it returns. - -| Without Sprinter | With Sprinter | -|---|---| -| User sells ETH to get USDC | User locks ETH, draws USDC — keeps ETH exposure | -| stETH sits in wallet earning yield but illiquid | stETH earns yield **and** backs a spendable credit line | -| User bridges to get stablecoins on another chain | Cross-chain collateral — one credit line, any chain | -| No spending power without selling | Instant USDC credit against existing portfolio | - -
-```mermaid -flowchart TD - A[User locks ETH / stETH as collateral] --> B[Credit line activated] - B --> C[User draws USDC from credit line] - C --> D[USDC sent to any address — pay, transfer, swap] - D --> E[User repays when ready] - E --> F[Collateral unlocked — ETH / stETH returned] -``` -
- -Every Sprinter endpoint returns `{ calls: ContractCall[] }` — unsigned transaction calldata. Your wallet signs and submits. No custody handoff. - -## What You Need from Sprinter - -| Your wallet handles | Sprinter handles | -|---|---| -| Wallet UX, account management | Collateral locking & credit line activation | -| Transaction signing & submission | USDC credit draws to any receiver address | -| Portfolio display, balance tracking | Health factor monitoring, LTV enforcement | -| Network switching, gas estimation | Earn vaults (collateral earns yield while locked) | -| User authentication | Repayment & collateral unlock | - -## Supported Collateral - -Users can lock assets they already hold. Each asset has its own LTV based on its risk profile: - -| Asset | LTV | Collateral Tier | Notes | -|---|:---:|---|---| -| ETH | 80% | Raw volatile | Native ETH — highest liquidity | -| stETH | 75% | Volatile DEX-swap | Lido staked ETH — earns staking yield while locked | -| wstETH | 75% | Volatile DEX-swap | Wrapped stETH — same yield, no rebase | -| USDC | 90% | Raw stablecoin | Stablecoin — highest LTV | - -Use `GET /credit/protocol` to fetch the latest supported assets and LTVs. See [Supported Assets](/sprinter-credit/supported-assets) for the full list and collateral tier framework. - -## Before You Start - -For most wallet integrations, users sign every transaction themselves — no delegation needed. A standard EOA (existing wallet) works out of the box. - -If you want to support features like auto-repayment, scheduled draws, or agent-assisted actions, you'll need a delegation model. See [Credit Accounts](/sprinter-credit/credit-accounts) for EOA + Operator vs Smart Account trade-offs, and [Credit Operators](/sprinter-credit/policy-engine#credit-operators) for how delegation works. - -## Integration - - - - When a user wants to borrow, they lock collateral from their wallet. The API returns calldata — your wallet signs and submits. - - - - ```bash - # Lock 1 ETH as collateral on Base - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/lock?amount=1000000000000000000&asset=0xETH_ADDRESS' - ``` - - - ```bash - # Lock stETH as collateral - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/lock?amount=1000000000000000000&asset=0xSTETH_ADDRESS' - ``` - - - ```bash - # Lock collateral and wrap into a yield-bearing vault - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/lock?amount=1000000000000000000&asset=0xCOLLATERAL&earn=STRATEGY_ID' - ``` - The `earn` parameter wraps the asset into a yield-bearing vault — collateral earns while the credit line is active. Use `GET /credit/protocol` for available strategies. - - - - Returns `{ calls: ContractCall[] }` — present to the user for signing. Once confirmed, the credit line is active. - - - - After locking, display the user's credit position in your wallet UI. - - ```bash - curl -X GET https://api.sprinter.tech/credit/accounts/0xUSER/info - ``` - - ```json - { - "data": { - "USDC": { - "totalCreditCapacity": "2400.00", - "remainingCreditCapacity": "2400.00", - "totalCollateralValue": "3000.00", - "principal": "0", - "interest": "0", - "healthFactor": "Infinity", - "dueDate": null - } - } - } - ``` - - Key fields to surface in your UI: - - | Field | What to show | - |---|---| - | `remainingCreditCapacity` | Available to borrow | - | `totalCollateralValue` | Total locked collateral value | - | `principal` + `interest` | Outstanding debt | - | `healthFactor` | Position health (warn below 1.5, danger below 1.2) | - | `dueDate` | Repayment deadline | - - - - When the user wants to borrow, draw USDC to any address — their own wallet, a merchant, a DEX, another wallet. - - ```bash - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/draw?amount=500000000&receiver=0xRECEIVER' - ``` - - | Parameter | Description | - |---|---| - | `account` | User's wallet address (borrower) | - | `amount` | USDC amount (6 decimals — $500 = `500000000`) | - | `receiver` | Any address — user's wallet, merchant, protocol | - - Returns `{ calls: ContractCall[] }` — user signs, USDC is delivered. - - - A **0.50% origination fee** is deducted from each draw. See [Fees](/sprinter-credit/credit-engine#fees). - - - - - Users repay debt to free their collateral. Anyone can repay on behalf of any account. - - ```bash - # Check outstanding debt - curl -X GET https://api.sprinter.tech/credit/accounts/0xUSER/info - - # Repay - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/repay?amount=500000000' - - # Unlock collateral - curl -X GET 'https://api.sprinter.tech/credit/accounts/0xUSER/unlock?amount=1000000000000000000&asset=0xCOLLATERAL' - ``` - - Credit runs on a 30-day billing cycle with a 7-day grace period. See [Fees](/sprinter-credit/credit-engine#fees). - - - -## UX Patterns - - - - WalletConnect Pay enables in-app payments. With Sprinter Credit, users can pay with USDC drawn against their ETH/stETH — no selling required. - - **Flow:** - 1. User initiates a payment via WalletConnect Pay - 2. Your app checks if the user has a Sprinter credit line with sufficient capacity - 3. If yes — draw USDC to the merchant/recipient via `/draw` - 4. User signs one transaction (the draw), payment is settled - 5. User repays later from any source - - **What happens after draw:** USDC lands directly in the merchant's or recipient's wallet. The payment is settled on-chain — no intermediary, no delay. The user paid with credit backed by their ETH, and the merchant received real USDC. - - This turns every ETH/stETH holder into a USDC spender without any sell pressure. - - - Display Sprinter Credit as a feature within the wallet's portfolio view. - - **UX:** - - Show "Available Credit" alongside token balances - - "Borrow" button next to eligible collateral (ETH, stETH) - - Health factor gauge with color coding (green → yellow → red) - - Repayment reminder before due date - - **What happens after draw:** When the user draws, USDC arrives in their wallet instantly — ready to send, swap, or spend. It feels like unlocking liquidity that was always there, just locked up in ETH. - - Users treat it like an overdraft — they see available credit and draw when needed. - - - When a user tries to swap or purchase but lacks stablecoins, offer credit as an alternative to selling. - - **Flow:** - 1. User wants to buy an NFT / swap for a token but has no USDC - 2. Prompt: "Borrow $X against your ETH instead of selling?" - 3. User confirms → lock ETH, draw USDC, complete purchase - 4. User repays within 30 days - - **What happens after draw:** The USDC goes directly to the seller or protocol — the NFT lands in the user's wallet, the swap executes, the purchase completes. The user got what they wanted without selling a single asset. They repay on their own schedule. - - This prevents forced selling and keeps users' long positions intact. - - - Users can send USDC to friends, family, or other wallets — funded by their credit line instead of their token balance. - - **Flow:** - 1. User wants to send $200 to a friend but only holds ETH - 2. User draws USDC with the friend's address as the `receiver` - 3. USDC arrives in the friend's wallet — one transaction - - **What happens after draw:** The friend receives USDC directly — no intermediate step, no swap. The sender's ETH stays locked and earning yield. This makes credit-backed transfers as simple as a regular wallet send. - - - Let users interact with DeFi protocols using borrowed USDC — provide liquidity, enter yield positions, or fund a DEX trade. - - **Flow:** - 1. User wants to provide liquidity on a DEX but doesn't want to sell ETH for the USDC side - 2. User draws USDC from their credit line - 3. USDC is used to enter the LP position alongside their existing tokens - - **What happens after draw:** The drawn USDC goes to the user's wallet or directly to a protocol address. The user is now earning LP fees on borrowed USDC while their ETH collateral continues earning staking yield — yield on both sides. - - - -## Integration Notes - - - - Poll `healthFactor` from the info endpoint and surface alerts in your wallet UI. A health factor approaching 1.0 means the position is close to liquidation — prompt the user to add collateral or repay. See [Risk Management](/sprinter-credit/risk-management). - - - Use the `earn` parameter when locking to wrap collateral into a yield-bearing vault. For stETH users, this means earning staking yield **and** vault yield simultaneously. Use `GET /credit/protocol` to discover available strategies. - - - Sprinter returns unsigned calldata — the user's wallet signs everything. Sprinter never has access to user funds. This means your wallet integration doesn't change your custody model. - - - If your users sign every transaction themselves, a standard EOA (existing wallet) is all you need. If you want to enable delegated actions like auto-repayment or scheduled draws, you'll need to choose between an Operator contract or Smart Account. See [Credit Accounts](/sprinter-credit/credit-accounts) for the full comparison. - - - ETH and stETH prices fluctuate. If collateral value drops, the health factor decreases and the user may face liquidation. Build alerts into your wallet UI — warn at health factor 1.5, strongly warn at 1.2. - - - Users can lock collateral on any supported chain. Sprinter handles cross-chain accounting — one credit line across all chains. This means users don't need to bridge assets before borrowing. - - - -## API Reference - -Every step maps to a single Sprinter endpoint: - -| Wallet Flow | Sprinter API | -|---|---| -| User locks collateral | `GET /credit/accounts/{account}/lock` | -| Lock + earn vault | `GET /credit/accounts/{account}/lock?earn=STRATEGY_ID` | -| Show credit position | `GET /credit/accounts/{account}/info` | -| Draw USDC | `GET /credit/accounts/{account}/draw?receiver={addr}` | -| Repay debt | `GET /credit/accounts/{account}/repay` | -| Unlock collateral | `GET /credit/accounts/{account}/unlock` | -| Get protocol config | `GET /credit/protocol` | - - - - Core credit draw lifecycle — lock, draw, repay, unlock. - - - Full collateral list, LTVs, and earn strategies. - - - Full API reference with interactive playground. - -