xpbonds

README

XP Bonds

Serverless solution to parse and analyze bond reports from XP Investments. It was built to run in AWS Lambda service. There's also a common HTTP server solution that can be used in other environments.

How does it works?

The service receives the Focused Lists report from XP Investments, in Excel format (xlsx), like the bellow.

The Excel report will be analyzed filtering undesired bonds with the following rules:

• Minimum coupon rate
• Maturity
• Price

The resulted bonds will be sorted by coupon. Current market price will also be retrieved to compare with the report (when available).

Serveless Setup

% go get -u github.com/rafaeljusto/xpbonds/...
% cd $GOPATH/github.com/rafaeljusto/xpbonds/cmd/xpbonds-serveless
% GOOS=linux go build -o xpbonds *.go && zip xpbonds.zip ./xpbonds
% aws lambda create-function \
  --region <region> \
  --function-name xpbonds \
  --memory 512 \
  --role <arn:aws:iam::account-id:role/execution_role> \
  --runtime go1.x \
  --zip-file fileb://$GOPATH/github.com/rafaeljusto/xpbonds/xpbonds.zip \
  --handler xpbonds

Serveless Protocol

The JSON that the service is expecting a events.APIGatewayProxyRequest, where the method should be POST and the body should be:

{
  "xlsxReport": "EsDBBQABgAIAAAAIQBG8ICPdQEAAD...BQYAAAAADwAPAN4DAABChAEAAAA=",
  "dateFormat": "MM/DD/YYYY",
  "minCoupon": 5,
  "maxMaturity": 6,
  "minPrice": 95,
  "maxPrice": 101,
  "minPiece": 0,
  "maxPiece": 400000
}

Where:

• xlsxReport is the XLSX report encoded in base64;
• dateFormat defines the date format used in the report, possible values are MM/DD/YYYY or DD/MM/YYYY;
• minCoupon will filter bonds that have a coupon rate (%) less than the provided;
• maxMaturity defined in years also will filter bonds with an expiration date too far away;
• minPrice and maxPrice defines a range of acceptable market prices for the bonds;
• minPiece and maxPiece defines a range of acceptable minimum piece of a bond;
• focusedOnly flag to determinate if only XP suggested bonds should be analyzed.

CORS is enable to make it easy for cross-domain requests. The response will be a events.APIGatewayProxyResponse, where the body will contain a list of bonds in the following format:

[
  {
    "name": "Gol Linhas Aereas Inteligentes",
    "security": "GOLLBZ 8 7/8 01/24/22",
    "coupon": 8.875,
    "yield": 8.6,
    "maturity": "2022-01-24T00:00:00Z",
    "lastPrice": 100.4,
    "duration": 1.8,
    "yearsToMaturity": 3.1,
    "minimumPiece": 200000,
    "country": "BR",
    "risk": {
      "standardPoor": "B-",
      "moody": "n.a.",
      "fitch": "B"
    },
    "code": "USL4441PAA86"
  }
]

PS: maturity could be null when the bond has no end date.

User Interface

There's a simple user web interface to easy retrieve the best bonds. If you decide using it, please remember to replace an internal URL for your production server.

Documentation

Index

• Constants
• type Bond
  • func (b Bond) Interesting(f Filter) bool
• type BondReport
• type BondRisk
• type Bonds
  • func FindBestBonds(ctx context.Context, report BondReport) (Bonds, error)
  • func (b Bonds) FillCurrentPrice()
  • func (b Bonds) Filter(f Filter) Bonds
  • func (b Bonds) Len() int
  • func (b Bonds) Less(i, j int) bool
  • func (b Bonds) Swap(i, j int)
• type DateFormat
  • func (d *DateFormat) UnmarshalJSON(data []byte) error
• type Duration
  • func (d *Duration) UnmarshalJSON(b []byte) error
• type Filter

Constants

const (
	DateFormatDDMMYYYY = "dd/mm/yyyy"
	DateFormatMMDDYYYY = "mm/dd/yyyy"
)

List of available date formats.

Types

type Bond

type Bond struct {
	Name            string     `json:"name"`
	Security        string     `json:"security"`
	Coupon          float64    `json:"coupon"`
	Yield           float64    `json:"yield"`
	Maturity        *time.Time `json:"maturity"`
	LastPrice       float64    `json:"lastPrice"`
	CurrentPrice    *float64   `json:"currentPrice"`
	CurrentPriceURL *string    `json:"currentPriceURL"`
	Accrued         float64    `json:"accrued"`
	AccruedDays     int64      `json:"accruedDays"`
	Duration        float64    `json:"duration"`
	YearsToMaturity float64    `json:"yearsToMaturity"`
	MinimumPiece    float64    `json:"minimumPiece"`
	Country         string     `json:"country"`
	Risk            BondRisk   `json:"risk"`
	Code            string     `json:"code"`
}

Bond contains the bond descriptions.

func (Bond) Interesting

func (b Bond) Interesting(f Filter) bool

Interesting returns if the bond is interesting according to some predefined rules.

type BondReport

type BondReport struct {
	Filter

	XLXSReport string     `json:"xlsxReport"`
	DateFormat DateFormat `json:"dateFormat"`
}

BondReport contains all bonds data to be analyzed.

type BondRisk

type BondRisk struct {
	StandardPoor string `json:"standardPoor"`
	Moody        string `json:"moody"`
	Fitch        string `json:"fitch"`
}

BondRisk determinates the risk according to different entities.

type Bonds

type Bonds []Bond

Bonds is a collection of Bond.

func FindBestBonds

func FindBestBonds(ctx context.Context, report BondReport) (Bonds, error)

FindBestBonds determinates the best bonds from the bond report. It expects the report to contain a xlsx content (Excel) encoded in base64. After parsing the xlxs it performs some filtering and sorting actions to determinate the best bond.

func (Bonds) FillCurrentPrice

func (b Bonds) FillCurrentPrice()

FillCurrentPrice looks for the current price from the given bonds.

func (Bonds) Filter

func (b Bonds) Filter(f Filter) Bonds

Filter detect the most interesting bonds according to some predefined rules.

func (Bonds) Len

func (b Bonds) Len() int

func (Bonds) Less

func (b Bonds) Less(i, j int) bool

func (Bonds) Swap

func (b Bonds) Swap(i, j int)

type DateFormat

type DateFormat string

DateFormat defines all acceptable date formats used when parsing the report.

func (*DateFormat) UnmarshalJSON

func (d *DateFormat) UnmarshalJSON(data []byte) error

UnmarshalJSON parse the date format input value. It will return an error if the date format isn't acceptable.

type Duration

type Duration struct {
	time.Duration
}

Duration stores the duration in years.

func (*Duration) UnmarshalJSON

func (d *Duration) UnmarshalJSON(b []byte) error

UnmarshalJSON parse and store a duration in years.

type Filter

type Filter struct {
	MinimumCoupon   float64  `json:"minCoupon"`
	MaximumMaturity Duration `json:"maxMaturity"`
	MinimumPrice    float64  `json:"minPrice"`
	MaximumPrice    float64  `json:"maxPrice"`
	MinimumPiece    float64  `json:"minPiece"`
	MaximumPiece    float64  `json:"maxPiece"`
	FocusedOnly     bool     `json:"focusedOnly"`
}

Filter contains all filters that can be used to determinate the best bond.