{
  "openapi": "3.1.0",
  "info": {
    "title": "717 Capital Partner API",
    "version": "1.0.0",
    "description": "USD ⇄ stablecoin (USDC, USDT) deposits and withdrawals for your users across Polygon, Ethereum, Base, Arbitrum, Optimism and Solana, with identity verification. Authenticate every request with `Authorization: Bearer <your key>`."
  },
  "servers": [
    {
      "url": "https://api.717capital.io/v1",
      "description": "Sandbox (branded)"
    },
    {
      "url": "https://nvsuwrmeqmpqvqmccsvn.supabase.co/functions/v1/partner-api",
      "description": "Sandbox (direct)"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "717_test_… in sandbox, 717_live_… in production"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable message"
          },
          "code": {
            "type": "string",
            "examples": [
              "invalid_request",
              "asset_unavailable_in_sandbox",
              "unauthorized",
              "user_not_found",
              "user_not_approved",
              "no_deposit_account",
              "conflict",
              "upstream_error",
              "internal_error"
            ]
          },
          "details": {}
        }
      },
      "BankDetails": {
        "type": "object",
        "description": "Where the user sends USD. Account is in the user's own name.",
        "properties": {
          "bank_name": {
            "type": "string"
          },
          "account_holder_name": {
            "type": "string"
          },
          "aba_routing_number": {
            "type": "string"
          },
          "account_number": {
            "type": "string"
          },
          "account_type": {
            "type": "string"
          },
          "bank_address": {
            "type": "object"
          }
        },
        "additionalProperties": true
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "external_user_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "not_started",
              "pending",
              "partner_review",
              "approved",
              "rejected",
              "frozen"
            ]
          },
          "application_status": {
            "type": [
              "string",
              "null"
            ]
          },
          "can_transact": {
            "type": "boolean"
          },
          "verification_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Send the user here to verify their identity. Null once approved. A fresh link is issued on each read; each is valid for 30 days."
          },
          "return_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "deposit": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "account_id": {
                "type": "string"
              },
              "delivers_to_wallet": {
                "type": "string"
              },
              "network": {
                "$ref": "#/components/schemas/Network"
              },
              "asset": {
                "type": "string",
                "examples": [
                  "USDC"
                ]
              },
              "rail": {
                "type": "string",
                "examples": [
                  "ach"
                ]
              },
              "bank_details": {
                "$ref": "#/components/schemas/BankDetails"
              },
              "network_id": {
                "type": "string",
                "examples": [
                  "polygon-amoy",
                  "polygon-mainnet"
                ]
              }
            }
          },
          "withdrawal": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "account_id": {
                "type": "string"
              },
              "send_usdc_to": {
                "type": "string",
                "description": "Alias of send_to"
              },
              "network": {
                "$ref": "#/components/schemas/Network"
              },
              "asset": {
                "type": "string"
              },
              "pays_out_to_bank_ending": {
                "type": "string"
              },
              "rail": {
                "type": "string"
              },
              "send_to": {
                "type": "string",
                "description": "Address to send the stablecoin to"
              },
              "network_id": {
                "type": "string"
              }
            }
          },
          "environment": {
            "type": "string",
            "enum": [
              "sandbox",
              "production"
            ]
          },
          "deposits": {
            "type": "array",
            "items": {
              "properties": {
                "account_id": {
                  "type": "string"
                },
                "delivers_to_wallet": {
                  "type": "string"
                },
                "network": {
                  "$ref": "#/components/schemas/Network"
                },
                "asset": {
                  "type": "string",
                  "examples": [
                    "USDC"
                  ]
                },
                "rail": {
                  "type": "string",
                  "examples": [
                    "ach"
                  ]
                },
                "bank_details": {
                  "$ref": "#/components/schemas/BankDetails"
                },
                "network_id": {
                  "type": "string",
                  "examples": [
                    "polygon-amoy",
                    "polygon-mainnet"
                  ]
                }
              },
              "type": "object"
            }
          },
          "withdrawals": {
            "type": "array",
            "items": {
              "properties": {
                "account_id": {
                  "type": "string"
                },
                "send_usdc_to": {
                  "type": "string",
                  "description": "Alias of send_to"
                },
                "network": {
                  "$ref": "#/components/schemas/Network"
                },
                "asset": {
                  "type": "string"
                },
                "pays_out_to_bank_ending": {
                  "type": "string"
                },
                "rail": {
                  "type": "string"
                },
                "send_to": {
                  "type": "string",
                  "description": "Address to send the stablecoin to"
                },
                "network_id": {
                  "type": "string"
                }
              },
              "type": "object"
            }
          }
        }
      },
      "Transaction": {
        "type": "object",
        "properties": {
          "transaction_id": {
            "type": "string"
          },
          "direction": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "deposit",
              "withdrawal",
              null
            ]
          },
          "status": {
            "type": "string",
            "examples": [
              "pending",
              "processing",
              "completed",
              "failed",
              "returned",
              "reversed"
            ]
          },
          "amount_in": {
            "type": [
              "number",
              "null"
            ]
          },
          "currency_in": {
            "type": [
              "string",
              "null"
            ]
          },
          "amount_out": {
            "type": [
              "number",
              "null"
            ]
          },
          "currency_out": {
            "type": [
              "string",
              "null"
            ]
          },
          "tx_hash": {
            "type": [
              "string",
              "null"
            ]
          },
          "hold_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Address": {
        "type": "object",
        "required": [
          "street1",
          "city",
          "country"
        ],
        "properties": {
          "street1": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "region": {
            "type": "string",
            "description": "Two-letter state code for US addresses"
          },
          "postal_code": {
            "type": "string"
          },
          "country": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2"
          }
        }
      },
      "Network": {
        "type": "string",
        "enum": [
          "polygon",
          "ethereum",
          "base",
          "arbitrum",
          "optimism",
          "solana"
        ],
        "default": "polygon"
      },
      "Asset": {
        "type": "string",
        "enum": [
          "USDC",
          "USDT"
        ],
        "default": "USDC",
        "description": "USDT is production-only for now"
      }
    },
    "responses": {
      "Error": {
        "description": "Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "User": {
        "description": "The user",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/User"
            }
          }
        }
      }
    },
    "parameters": {
      "ExternalUserId": {
        "name": "external_user_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Your own ID for the user"
      }
    }
  },
  "paths": {
    "/ping": {
      "get": {
        "summary": "Check your API key",
        "responses": {
          "200": {
            "description": "Key works",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "partner": {
                      "type": "string"
                    },
                    "environment": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/users": {
      "post": {
        "summary": "Create a user and start identity verification",
        "description": "Idempotent on external_user_id: calling again returns the existing user (200).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "external_user_id",
                  "name"
                ],
                "properties": {
                  "external_user_id": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "individual",
                      "business"
                    ],
                    "default": "individual"
                  },
                  "return_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "https URL to send the user back to after verification"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/User"
          },
          "200": {
            "$ref": "#/components/responses/User"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/users/{external_user_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ExternalUserId"
        }
      ],
      "get": {
        "summary": "Get a user's status and account details",
        "responses": {
          "200": {
            "$ref": "#/components/responses/User"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/users/{external_user_id}/deposit-account": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ExternalUserId"
        }
      ],
      "post": {
        "summary": "Create the user's USD deposit account (USD → USDC to their wallet)",
        "description": "Requires an approved user. Calling again with the same wallet, network and asset returns the same account.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet_address"
                ],
                "properties": {
                  "wallet_address": {
                    "type": "string",
                    "description": "0x… for EVM networks, base58 for Solana"
                  },
                  "network": {
                    "$ref": "#/components/schemas/Network"
                  },
                  "asset": {
                    "$ref": "#/components/schemas/Asset"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/User"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/users/{external_user_id}/withdrawal-account": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ExternalUserId"
        }
      ],
      "post": {
        "summary": "Create the user's withdrawal account (USDC → USD to their bank)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "routing_number",
                  "account_number",
                  "account_holder_name",
                  "bank_name"
                ],
                "properties": {
                  "routing_number": {
                    "type": "string",
                    "pattern": "^\\d{9}$"
                  },
                  "account_number": {
                    "type": "string",
                    "pattern": "^\\d{4,17}$"
                  },
                  "account_type": {
                    "type": "string",
                    "enum": [
                      "checking",
                      "savings"
                    ],
                    "default": "checking"
                  },
                  "account_holder_name": {
                    "type": "string"
                  },
                  "bank_name": {
                    "type": "string"
                  },
                  "address": {
                    "$ref": "#/components/schemas/Address"
                  },
                  "network": {
                    "$ref": "#/components/schemas/Network"
                  },
                  "asset": {
                    "$ref": "#/components/schemas/Asset"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/User"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/users/{external_user_id}/transactions": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ExternalUserId"
        }
      ],
      "get": {
        "summary": "List the user's conversions (newest first, up to 100)",
        "responses": {
          "200": {
            "description": "Transactions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Transaction"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/sandbox/users/{external_user_id}/approve": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ExternalUserId"
        }
      ],
      "post": {
        "summary": "Sandbox only: approve the user's verification instantly",
        "responses": {
          "200": {
            "$ref": "#/components/responses/User"
          }
        }
      }
    },
    "/sandbox/users/{external_user_id}/deposit": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ExternalUserId"
        }
      ],
      "post": {
        "summary": "Sandbox only: simulate a USD deposit into the user's deposit account",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount": {
                    "type": "number",
                    "minimum": 0.01,
                    "maximum": 2,
                    "default": 1
                  },
                  "rail": {
                    "type": "string",
                    "enum": [
                      "ach",
                      "wire"
                    ],
                    "default": "ach"
                  },
                  "network": {
                    "$ref": "#/components/schemas/Network"
                  },
                  "asset": {
                    "$ref": "#/components/schemas/Asset"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted. Conversion events follow by webhook."
          },
          "409": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/networks": {
      "get": {
        "summary": "Networks and stablecoins available in this environment",
        "responses": {
          "200": {
            "description": "Supported rails",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "environment": {
                      "type": "string"
                    },
                    "default": {
                      "type": "object"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "network": {
                            "$ref": "#/components/schemas/Network"
                          },
                          "label": {
                            "type": "string"
                          },
                          "network_id": {
                            "type": "string"
                          },
                          "address_format": {
                            "type": "string"
                          },
                          "assets": {
                            "type": "array",
                            "items": {
                              "$ref": "#/components/schemas/Asset"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}