{
  "openapi": "3.1.0",
  "info": {
    "title": "PinkWallet API",
    "version": "2026-07-11",
    "summary": "Payments, multi-currency accounts, and conversion over a clean REST API.",
    "description": "Programmatic access to the same rails that power the PinkWallet app. All amounts are decimal strings; all timestamps are ISO-8601 in UTC. Responses are normalised by the PinkWallet Orchestration Layer and never expose an underlying banking or liquidity provider.",
    "contact": { "name": "PinkWallet Developer Support", "url": "https://api.pinkwallet.com" }
  },
  "servers": [
    { "url": "https://api.pinkwallet.com/v1", "description": "Production" },
    { "url": "https://api.pinkwallet.com/sandbox/v1", "description": "Sandbox (pk_test_ keys)" }
  ],
  "security": [ { "bearerAuth": [] } ],
  "tags": [
    { "name": "Payment Links" }, { "name": "Bank Accounts" }, { "name": "Convert" },
    { "name": "Buy Crypto" }, { "name": "Balances" }, { "name": "Transactions" }
  ],
  "paths": {
    "/payment_links": {
      "post": {
        "tags": ["Payment Links"], "operationId": "createPaymentLink",
        "summary": "Create a payment link",
        "description": "Generate a shareable link that collects a USDT or USDC payment on-chain.",
        "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkCreate" } } } },
        "responses": { "200": { "description": "The created payment link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" } }
      },
      "get": {
        "tags": ["Payment Links"], "operationId": "listPaymentLinks",
        "summary": "List payment links",
        "parameters": [
          { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending", "paid", "expired", "cancelled"] } }
        ],
        "responses": { "200": { "description": "A paginated list of payment links.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" } } } } ] } } } } }
      }
    },
    "/payment_links/{id}": {
      "get": {
        "tags": ["Payment Links"], "operationId": "retrievePaymentLink", "summary": "Retrieve a payment link",
        "parameters": [ { "$ref": "#/components/parameters/PathId" } ],
        "responses": { "200": { "description": "The payment link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "404": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/payment_links/{id}/cancel": {
      "post": {
        "tags": ["Payment Links"], "operationId": "cancelPaymentLink", "summary": "Cancel a payment link",
        "parameters": [ { "$ref": "#/components/parameters/PathId" } ],
        "responses": { "200": { "description": "The cancelled payment link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "402": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/accounts": {
      "get": {
        "tags": ["Bank Accounts"], "operationId": "listAccounts", "summary": "List accounts",
        "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" } } ],
        "responses": { "200": { "description": "Your multi-currency accounts.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } } ] } } } } }
      }
    },
    "/accounts/{id}": {
      "get": {
        "tags": ["Bank Accounts"], "operationId": "retrieveAccount", "summary": "Retrieve an account",
        "parameters": [ { "$ref": "#/components/parameters/PathId" } ],
        "responses": { "200": { "description": "The account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "404": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/convert/quotes": {
      "post": {
        "tags": ["Convert"], "operationId": "createConvertQuote", "summary": "Create a quote",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertQuoteCreate" } } } },
        "responses": { "200": { "description": "A firm, time-limited quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertQuote" } } } } }
      }
    },
    "/convert": {
      "post": {
        "tags": ["Convert"], "operationId": "createConversion", "summary": "Create a conversion",
        "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionCreate" } } } },
        "responses": { "200": { "description": "The executed conversion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversion" } } } }, "402": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/convert/{id}": {
      "get": {
        "tags": ["Convert"], "operationId": "retrieveConversion", "summary": "Retrieve a conversion",
        "parameters": [ { "$ref": "#/components/parameters/PathId" } ],
        "responses": { "200": { "description": "The conversion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversion" } } } } }
      }
    },
    "/buy/assets": {
      "get": {
        "tags": ["Buy Crypto"], "operationId": "listBuyAssets", "summary": "List supported assets",
        "responses": { "200": { "description": "Available fiats and crypto assets.", "content": { "application/json": { "schema": { "type": "object", "properties": { "fiats": { "type": "array", "items": { "type": "string" } }, "assets": { "type": "array", "items": { "type": "string" } } } } } } } }
      }
    },
    "/buy/quotes": {
      "post": {
        "tags": ["Buy Crypto"], "operationId": "createBuyQuote", "summary": "Create a buy quote",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyQuoteCreate" } } } },
        "responses": { "200": { "description": "A firm buy quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyQuote" } } } } }
      }
    },
    "/buy_orders": {
      "post": {
        "tags": ["Buy Crypto"], "operationId": "createBuyOrder", "summary": "Create a buy order",
        "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyOrderCreate" } } } },
        "responses": { "200": { "description": "The buy order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyOrder" } } } }, "402": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/buy_orders/{id}": {
      "get": {
        "tags": ["Buy Crypto"], "operationId": "retrieveBuyOrder", "summary": "Retrieve a buy order",
        "parameters": [ { "$ref": "#/components/parameters/PathId" } ],
        "responses": { "200": { "description": "The buy order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyOrder" } } } } }
      }
    },
    "/balances": {
      "get": {
        "tags": ["Balances"], "operationId": "listBalances", "summary": "List balances",
        "parameters": [ { "name": "asset", "in": "query", "schema": { "type": "string" } } ],
        "responses": { "200": { "description": "Balances across every asset.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Balance" } } } } ] } } } } }
      }
    },
    "/transactions": {
      "get": {
        "tags": ["Transactions"], "operationId": "listTransactions", "summary": "List transactions",
        "parameters": [
          { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" },
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["deposit", "payout", "conversion", "payment"] } }
        ],
        "responses": { "200": { "description": "A paginated list of transactions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } } ] } } } } }
      }
    },
    "/transactions/{id}": {
      "get": {
        "tags": ["Transactions"], "operationId": "retrieveTransaction", "summary": "Retrieve a transaction",
        "parameters": [ { "$ref": "#/components/parameters/PathId" } ],
        "responses": { "200": { "description": "The transaction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } } }
      }
    }
  },
  "webhooks": {
    "paymentLinkPaid": {
      "post": {
        "summary": "payment_link.paid", "description": "Sent when a payment link receives its funds on-chain. Verify the X-PW-Signature header.",
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } },
        "responses": { "200": { "description": "Return 2xx within 5s to acknowledge." } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "pk_live_ / pk_test_", "description": "Pass your secret API key as a bearer token. Write operations are additionally HMAC-signed via X-PW-Signature." }
    },
    "parameters": {
      "PathId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
      "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } },
      "StartingAfter": { "name": "starting_after", "in": "query", "schema": { "type": "string" }, "description": "A resource id; returns the page after it." },
      "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" }, "description": "A unique key to make this write safely retryable for 24 hours." }
    },
    "responses": {
      "Error": { "description": "Error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Amount": { "type": "string", "description": "A decimal amount as a string, e.g. \"250.00\".", "example": "250.00" },
      "List": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": {} } } },
      "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } } } } },
      "PaymentLinkCreate": {
        "type": "object", "required": ["amount", "asset"],
        "properties": {
          "amount": { "$ref": "#/components/schemas/Amount" },
          "asset": { "type": "string", "enum": ["USDT", "USDC"] },
          "reference": { "type": "string", "maxLength": 128 },
          "expires_in": { "type": "integer", "default": 3600 },
          "metadata": { "type": "object", "additionalProperties": { "type": "string" } }
        }
      },
      "PaymentLink": {
        "type": "object",
        "properties": {
          "id": { "type": "string" }, "object": { "type": "string", "const": "payment_link" },
          "status": { "type": "string", "enum": ["pending", "paid", "expired", "cancelled"] },
          "amount": { "$ref": "#/components/schemas/Amount" }, "asset": { "type": "string" },
          "url": { "type": "string", "format": "uri" }, "address": { "type": "string" },
          "reference": { "type": "string" }, "tx_hash": { "type": "string" },
          "expires_at": { "type": "string", "format": "date-time" }, "paid_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Account": {
        "type": "object",
        "properties": {
          "id": { "type": "string" }, "object": { "type": "string", "const": "account" },
          "currency": { "type": "string" }, "status": { "type": "string", "enum": ["active", "pending", "review"] },
          "holder_name": { "type": "string" }, "account_number": { "type": "string" }, "routing_number": { "type": "string" }, "bank_address": { "type": "string" },
          "balance": { "$ref": "#/components/schemas/Amount" }
        }
      },
      "ConvertQuoteCreate": { "type": "object", "required": ["from_asset", "to_asset", "from_amount"], "properties": { "from_asset": { "type": "string" }, "to_asset": { "type": "string" }, "from_amount": { "$ref": "#/components/schemas/Amount" } } },
      "ConvertQuote": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "quote" }, "from_asset": { "type": "string" }, "to_asset": { "type": "string" }, "from_amount": { "$ref": "#/components/schemas/Amount" }, "to_amount": { "$ref": "#/components/schemas/Amount" }, "rate": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } },
      "ConversionCreate": { "type": "object", "properties": { "from_asset": { "type": "string" }, "to_asset": { "type": "string" }, "from_amount": { "$ref": "#/components/schemas/Amount" }, "quote_id": { "type": "string" } } },
      "Conversion": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "conversion" }, "status": { "type": "string", "enum": ["filled", "pending", "failed"] }, "from_asset": { "type": "string" }, "to_asset": { "type": "string" }, "from_amount": { "$ref": "#/components/schemas/Amount" }, "to_amount": { "$ref": "#/components/schemas/Amount" }, "rate": { "type": "string" }, "fee": { "$ref": "#/components/schemas/Amount" } } },
      "BuyQuoteCreate": { "type": "object", "required": ["fiat", "asset", "fiat_amount"], "properties": { "fiat": { "type": "string" }, "asset": { "type": "string" }, "fiat_amount": { "$ref": "#/components/schemas/Amount" } } },
      "BuyQuote": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "buy_quote" }, "fiat_amount": { "$ref": "#/components/schemas/Amount" }, "asset_amount": { "$ref": "#/components/schemas/Amount" }, "rate": { "type": "string" }, "fee": { "$ref": "#/components/schemas/Amount" } } },
      "BuyOrderCreate": { "type": "object", "required": ["fiat", "asset", "fiat_amount"], "properties": { "fiat": { "type": "string" }, "asset": { "type": "string" }, "fiat_amount": { "$ref": "#/components/schemas/Amount" }, "quote_id": { "type": "string" } } },
      "BuyOrder": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "buy_order" }, "status": { "type": "string", "enum": ["completed", "pending", "failed"] }, "fiat": { "type": "string" }, "fiat_amount": { "$ref": "#/components/schemas/Amount" }, "asset": { "type": "string" }, "asset_amount": { "$ref": "#/components/schemas/Amount" }, "rate": { "type": "string" }, "fee": { "$ref": "#/components/schemas/Amount" } } },
      "Balance": { "type": "object", "properties": { "asset": { "type": "string" }, "available": { "$ref": "#/components/schemas/Amount" }, "on_hold": { "$ref": "#/components/schemas/Amount" } } },
      "Transaction": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "transaction" }, "type": { "type": "string", "enum": ["deposit", "payout", "conversion", "payment"] }, "asset": { "type": "string" }, "amount": { "$ref": "#/components/schemas/Amount" }, "status": { "type": "string" }, "reference": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } },
      "Event": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": ["payment_link.paid", "deposit.credited", "conversion.filled", "buy_order.completed"] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object" } } }
    }
  }
}